feat(toolchain): iOS is an ecosystem compiler and a located SDK

D1/D2. THE THREE iOS ROWS PIN `llvm@22.1.8`. The sentence that shrank this
item is that the compiler is ours and only the SDK is Apple's: any
sufficiently new clang emits arm64 Mach-O for an iOS deployment target, and
`aarch64-macos` is verified on exactly that split. Xcode's clang would also
work and is the wrong default, because it would make the compiler a host
dependency where the ecosystem already has one.

A CONVENTION PIN, NOT A CAPABILITY ONE. It answers "what does `--target
aarch64-ios` resolve when the project says nothing" and stays overridable --
consistent with `aarch64-macos`, where the same constraint (Darwin needs
clang) holds and which is not a capability row either. The rows carry no
`sysroot`, because that column names a PACKAGE and an Apple SDK is located.

The deployment target travels in the EFFECTIVE TRIPLE and nowhere else:
`arm64-apple-ios18.0` and `arm64-apple-ios18.0-simulator`, Apple's own
spellings, which fully determine platform and minimum. `-miphoneos-version-min`
is deliberately not emitted -- it would be a second place answering a question
the triple already answers. macOS keeps its flag, and the asymmetry now has a
criterion of its own in the triple tests rather than being folded into this.

FOUR SITES HAD TO LEARN THAT A macOS HOST IS NOT A macOS TARGET.

  - hostflags emitted `-mmacosx-version-min` whenever the HOST was macOS. With
    an iOS triple clang refuses the combination outright, so the flag would
    stop the build rather than be ignored. Gated on the located SDK being
    empty, which is the same value that says "this is a cross".
  - the compile side gets `-isysroot <located SDK>`, which it never needed
    before: a native build reads the payload's `clang++.cfg`, and post-install
    filled that with the located macOS SDK. An Apple cross suppresses the cfg
    precisely because it names the wrong platform.
  - the LINK line in that branch carried no `--target` at all. The note two
    hundred lines below it records that only the third branch ever consumed
    `link_toolchain_flags`; an iOS row is the first target this branch serves
    that the driver would get wrong, and a link told nothing produces a macOS
    binary from objects compiled as iOS.
  - the Mach-O distribution cell chose the self-contained contract, which
    links the payload's `libc++.a` -- a Mach-O archive built for macOS, which
    ld64 refuses in an iOS link. iOS takes libc++ from the SDK, which every
    iOS release ships, and the floor stays real because the triple carries it.

`ios_deployment_target` in `[build]`, beside `macos_deployment_target`: one
fingerprint slot, two version spaces, because "14.0" is a macOS version and
means nothing to an iOS SDK.

THE SDK IS LOCATED ONCE AND ITS ABSENCE IS A REFUSAL THAT NAMES IT. Three
later sites need the answer and `xcrun` shells out, so probing three times
could return three answers. The refusal names the SDK, the `xcrun` command
that must answer, that Command Line Tools alone ship the macOS SDK only, and
that the compiler is not the problem.

AND THE PROBE TAUGHT THE MEASUREMENT ITS OWN LESSON. The first
ci-macos-ios.yml run answered the premise -- Xcode 16.4, iPhoneOS 18.5,
iPhoneSimulator 18.5, five iOS simulator runtimes, an iPhone 16 Pro that boots
-- and then failed with

  ld64.lld: error: .../MacOSX.sdk/usr/lib/libc++.tbd(...) is incompatible with
    arm64 (iOS Simulator18.0.0)

with the correct `-isysroot` on the command line: the payload's cfg won. That
is the fact behind three of the four sites above. The four steps after the
failing one were SKIPPED, so one unmet assumption cost the rest of the
measurement; every step is now `continue-on-error`, because a probe that stops
at the first `no` is a build and not a measurement.

A second job builds mcpp from this branch and asks the engine the same
questions: the device row's artefact and its `LC_BUILD_VERSION`, the simulator
row plus `simctl spawn` on the bare Mach-O -- which decides whether
`simctl-run` is a boot-and-spawn wrapper or has to synthesise a bundle -- and
that the refusal names the SDK while the host row still builds in the same
environment. The rows stay `planned` until those answers arrive; the fixture
uses the escape hatch the refusal itself advertises.

Author: speak-agent

.github/workflows/ci-macos-ios.yml

@@ -39,7 +39,14 @@ jobs:
       # the device row is still verifiable here and the two simulator rows
       # become a local-only claim -- which changes the tier they can reach and
       # nothing else. This step is the difference between those two worlds.
+      # EVERY MEASUREMENT STEP CONTINUES, because the first version of this job
+      # did not and the four steps after the failing one were SKIPPED -- so one
+      # unmet assumption cost the whole measurement. A probe's value is the
+      # complete set of answers; a probe that stops at the first `no` is a
+      # build, not a measurement. (GitHub runs `run:` under `bash -e`, which is
+      # what turned a failing clang into a terminated step.)
       - name: "Host surface: the two located SDKs and the simulator runtime"
+        continue-on-error: true
         run: |
           set -x
           xcode-select -p
@@ -59,7 +66,30 @@ jobs:
       # `simctl-run` program is a boot-and-spawn wrapper; if it does not, it
       # has to synthesise a bundle, sign it and install it. Measuring this is
       # cheaper than designing for the harder case.
+      # THE PAYLOAD'S CLANG READS A CONFIG FILE, AND THAT CONFIG NAMES A
+      # DIFFERENT SDK. First run, with `-isysroot <iPhoneSimulator18.5.sdk>`
+      # on the command line:
+      #
+      #   ld64.lld: error: /Library/Developer/CommandLineTools/SDKs/
+      #     MacOSX.sdk/usr/lib/libc++.tbd(/usr/lib/libc++.1.dylib) is
+      #     incompatible with arm64 (iOS Simulator18.0.0)
+      #
+      # mcpp's own post-install writes the located macOS SDK into the
+      # payload's `clang++.cfg` so that a native macOS build is deterministic,
+      # and that cfg is read before the command line for search purposes. So
+      # an Apple CROSS target has to suppress it -- which mcpp's cross path
+      # already does (`--no-default-config` in hostflags.cppm), and which this
+      # hand-written probe did not. Printed here because the explanation
+      # belongs next to the measurement.
+      - name: "The payload's default config, which is why --no-default-config"
+        continue-on-error: true
+        run: |
+          set -x
+          ls -la "$LLVM_ROOT/bin/"*.cfg || true
+          for f in "$LLVM_ROOT/bin/"*.cfg; do echo "=== $f"; cat "$f"; done || true
+
       - name: "Device: is one bootable, and does spawn take a bare executable"
+        continue-on-error: true
         run: |
           set -uo pipefail
           UDID=$(xcrun simctl list devices available \
@@ -71,15 +101,18 @@ jobs:
             exit 0
           fi
           xcrun simctl boot "$UDID" || true
-          xcrun simctl bootstatus "$UDID" -b || true
+          xcrun simctl bootstatus "$UDID" -b 2>&1 | tail -3 || true
           cat > /tmp/hello.cpp << 'CPP'
           #include <cstdio>
           int main() { std::puts("1-2-3"); return 0; }
           CPP
           SDK=$(xcrun --sdk iphonesimulator --show-sdk-path)
-          "$LLVM_ROOT/bin/clang++" -std=c++23 \
-            -target arm64-apple-ios18.0-simulator \
-            -isysroot "$SDK" -o /tmp/hello /tmp/hello.cpp
+          if ! "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+                 -target arm64-apple-ios18.0-simulator \
+                 -isysroot "$SDK" -o /tmp/hello /tmp/hello.cpp; then
+            echo "SIM-COMPILE-FAILED"
+            exit 0
+          fi
           file /tmp/hello
           otool -l /tmp/hello | grep -A5 LC_BUILD_VERSION || true
           echo "--- simctl spawn on a bare Mach-O ---"
@@ -95,14 +128,16 @@ jobs:
       # that says MACOS there is the failure this leg exists to catch, and it
       # is invisible to a build that merely succeeds.
       - name: "Device: the artefact names the iOS platform"
+        continue-on-error: true
         run: |
           set -euo pipefail
           cat > /tmp/dev.cpp << 'CPP'
           #include <cstdio>
           int main() { std::puts("1-2-3"); return 0; }
           CPP
           SDK=$(xcrun --sdk iphoneos --show-sdk-path)
-          "$LLVM_ROOT/bin/clang++" -std=c++23 -target arm64-apple-ios18.0 \
+          "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+            -target arm64-apple-ios18.0 \
             -isysroot "$SDK" -o /tmp/dev /tmp/dev.cpp
           file /tmp/dev
           otool -l /tmp/dev | grep -A5 LC_BUILD_VERSION
@@ -115,6 +150,7 @@ jobs:
       # works" is the fact the flag builder needs and neither answer can be
       # reasoned out from a Linux desk.
       - name: "C++ runtime: SDK libc++ versus the payload static archive"
+        continue-on-error: true
         run: |
           set -x
           SDK=$(xcrun --sdk iphoneos --show-sdk-path)
@@ -124,15 +160,17 @@ jobs:
           int main() { std::string s = "1-2-3"; std::puts(s.c_str()); return 0; }
           CPP
           echo "--- (a) SDK libc++, dynamic ---"
-          if "$LLVM_ROOT/bin/clang++" -std=c++23 -target arm64-apple-ios18.0 \
+          if "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+               -target arm64-apple-ios18.0 \
                -isysroot "$SDK" -o /tmp/cxx-sdk /tmp/cxx.cpp; then
             otool -L /tmp/cxx-sdk
             echo "SDK-LIBCXX-OK"
           else
             echo "SDK-LIBCXX-FAILED"
           fi
           echo "--- (b) payload static libc++ ---"
-          if "$LLVM_ROOT/bin/clang++" -std=c++23 -target arm64-apple-ios18.0 \
+          if "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+               -target arm64-apple-ios18.0 \
                -isysroot "$SDK" -nostdlib++ \
                "$LLVM_ROOT/lib/libc++.a" "$LLVM_ROOT/lib/libc++abi.a" \
                -o /tmp/cxx-static /tmp/cxx.cpp; then
@@ -148,13 +186,15 @@ jobs:
       # uses, with a second SDK. If this cannot be made to work the iOS rows
       # are a non-module tier and the documentation has to say so.
       - name: "import std: precompile against the located SDK"
+        continue-on-error: true
         run: |
           set -x
           SDK=$(xcrun --sdk iphoneos --show-sdk-path)
           STD_CPPM=$(find "$LLVM_ROOT" -name 'std.cppm' | head -1)
           echo "std.cppm=$STD_CPPM"
           MODDIR=$(dirname "$STD_CPPM")
-          if "$LLVM_ROOT/bin/clang++" -std=c++23 -target arm64-apple-ios18.0 \
+          if "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+               -target arm64-apple-ios18.0 \
                -isysroot "$SDK" -Wno-reserved-module-identifier \
                -Xclang -emit-reduced-module-interface \
                --precompile -o /tmp/std.pcm "$STD_CPPM" -I"$MODDIR"; then
@@ -166,7 +206,8 @@ jobs:
           import std;
           int main() { std::println("1-2-3"); return 0; }
           CPP
-          if "$LLVM_ROOT/bin/clang++" -std=c++23 -target arm64-apple-ios18.0 \
+          if "$LLVM_ROOT/bin/clang++" -std=c++23 --no-default-config \
+               -target arm64-apple-ios18.0 \
                -isysroot "$SDK" -fmodule-file=std=/tmp/std.pcm \
                -o /tmp/mod /tmp/mod.cpp /tmp/std.pcm; then
             echo "MODULE-LINK-OK"
@@ -175,3 +216,124 @@ jobs:
           fi
           file /tmp/mod || true
           set +x
+
+  ios-engine:
+    name: iOS - mcpp builds and the simulator runs it
+    runs-on: macos-15
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: ./.github/actions/setup-macos-llvm
+
+      - name: Build mcpp from source (self-host)
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          "$MCPP" build
+          echo "MCPP_DEV=$(ls -td "$PWD"/target/*/*/bin/mcpp | head -1)" >> "$GITHUB_ENV"
+
+      # THE THREE ROWS ARE `planned`, AND THAT IS THE STATE THIS JOB EXISTS TO
+      # CHANGE. A planned row is refused with its own escape hatch named:
+      #
+      #   error: target 'aarch64-ios' is registered but not yet supported
+      #          (planned) -- An explicit [target.aarch64-ios] toolchain
+      #          override can opt in early.
+      #
+      # so the fixture writes that override. Once this job is green the tiers
+      # move and the override becomes unnecessary; keeping it until then is
+      # what makes the measurement possible before the claim is made.
+      - name: "Fixture: a project that imports std and prints 1-2-3"
+        run: |
+          set -euo pipefail
+          mkdir -p /tmp/iostest/src
+          cat > /tmp/iostest/mcpp.toml << 'TOML'
+          [package]
+          name = "iostest"
+          version = "0.1.0"
+
+          [build]
+          ios_deployment_target = "18.0"
+
+          [target.aarch64-ios]
+          toolchain = "llvm@22.1.8"
+
+          [target.aarch64-ios-sim]
+          toolchain = "llvm@22.1.8"
+
+          [target.x86_64-ios-sim]
+          toolchain = "llvm@22.1.8"
+          TOML
+          cat > /tmp/iostest/src/main.cpp << 'CPP'
+          import std;
+          int main() {
+            std::vector<int> v{3, 1, 2};
+            std::ranges::sort(v);
+            std::print("{}-{}-{}\n", v[0], v[1], v[2]);
+          }
+          CPP
+          cat /tmp/iostest/mcpp.toml
+
+      # D1/D2: THE DEVICE ROW'S ARTEFACT. Nothing runs it -- that needs a
+      # signature the developer owns -- so the claim is about the artefact:
+      # arm64 Mach-O naming the iOS platform and the project's deployment
+      # target in LC_BUILD_VERSION. A build that merely succeeds cannot tell
+      # those apart from a macOS binary.
+      - name: "D1: mcpp build --target aarch64-ios"
+        continue-on-error: true
+        run: |
+          set -x
+          cd /tmp/iostest
+          "$MCPP_DEV" build --target aarch64-ios
+          set +x
+          ART=$(find /tmp/iostest/target/aarch64-ios -name iostest -type f | head -1)
+          echo "artefact=$ART"
+          file "$ART"
+          otool -l "$ART" | grep -A5 LC_BUILD_VERSION
+
+      # D4's PREMISE: whether `simctl spawn` takes a bare Mach-O. If it does,
+      # the `simctl-run` program in xim:apple-simulator-tools is a
+      # boot-and-spawn wrapper; if it does not, it has to synthesise a bundle,
+      # sign it and install it. This is the measurement that decides which.
+      - name: "D4: mcpp build --target aarch64-ios-sim, then simctl spawn"
+        continue-on-error: true
+        run: |
+          set -x
+          cd /tmp/iostest
+          "$MCPP_DEV" build --target aarch64-ios-sim
+          set +x
+          ART=$(find /tmp/iostest/target/aarch64-ios-sim -name iostest -type f | head -1)
+          echo "artefact=$ART"
+          file "$ART"
+          otool -l "$ART" | grep -A5 LC_BUILD_VERSION
+          UDID=$(xcrun simctl list devices available \
+                 | grep -A50 -- '-- iOS' \
+                 | grep -m1 -oE '[0-9A-F]{8}-[0-9A-F-]{27}' || true)
+          echo "udid=[$UDID]"
+          if [ -z "$UDID" ]; then echo "NO-IOS-SIMULATOR-DEVICE"; exit 0; fi
+          xcrun simctl boot "$UDID" || true
+          xcrun simctl bootstatus "$UDID" -b 2>&1 | tail -3 || true
+          if xcrun simctl spawn "$UDID" "$ART"; then
+            echo "SPAWN-OK"
+          else
+            echo "SPAWN-FAILED exit=$?"
+          fi
+
+      # THE HOST SURFACE IS BOUNDED, AND ITS ABSENCE NAMES THE SDK. The
+      # recorded rule is that a host dependency must be minimal, named, and
+      # never a fallthrough -- so the refusal is a claim like any other, and
+      # `SDKROOT` pointing at a macOS SDK is the cheapest way to make the iOS
+      # SDK unlocatable without breaking the rest of the machine.
+      #
+      # AND NO OTHER ROW CHANGES: the same environment builds for the host.
+      - name: "D: the refusal names the SDK, and no other row is affected"
+        continue-on-error: true
+        run: |
+          set -x
+          cd /tmp/iostest
+          DEVDIR=/nonexistent-developer-dir
+          env DEVELOPER_DIR="$DEVDIR" SDKROOT="" \
+            "$MCPP_DEV" build --target aarch64-ios 2>&1 | tail -12
+          set +x
+          echo "--- and the host row still builds in the same environment ---"
+          env DEVELOPER_DIR="$DEVDIR" "$MCPP_DEV" build 2>&1 | tail -4 || true

modules/toolchain-model/src/model.cppm

@@ -181,6 +181,30 @@ struct Toolchain {
     // zero-libc tier and on hosted targets.
     std::string                         targetSysrootPkg;
     std::filesystem::path               targetSysrootLib;
+    // THE APPLE SDK THIS TARGET WAS LOCATED AGAINST, and it is a different
+    // axis from the three paths above.
+    //
+    // `targetSysroot*` name a PACKAGE's directories -- a C library this
+    // ecosystem ships and can therefore version. An Apple SDK is located, not
+    // installed: the iPhoneOS and iPhoneSimulator headers and stub libraries
+    // ship inside Xcode and are not redistributable, so there is nothing for
+    // a package to name and the row carries no `sysroot` entry. What it
+    // carries instead is this, resolved once where the target is known.
+    //
+    // Empty for every non-Apple target AND for a native macOS build, which
+    // needs none: that build reads the payload's own `clang++.cfg`, and
+    // `post_install.cppm` wrote the located macOS SDK into it. An Apple CROSS
+    // target suppresses that cfg (`--no-default-config`) precisely because it
+    // names the wrong platform -- measured 2026-09-11 on macos-15, where an
+    // iOS-simulator link with the right `-isysroot` on the command line still
+    // picked the cfg's SDK:
+    //
+    //   ld64.lld: error: .../MacOSX.sdk/usr/lib/libc++.tbd(...) is
+    //     incompatible with arm64 (iOS Simulator18.0.0)
+    //
+    // so the SDK has to travel explicitly, on the compile side as well as the
+    // link side.
+    std::filesystem::path               appleSdkRoot;
     std::vector<std::filesystem::path>   compilerRuntimeDirs; // LD_LIBRARY_PATH for private tools
     std::vector<std::filesystem::path>   linkRuntimeDirs;     // -L/-rpath dirs for produced binaries
     // Environment the toolchain's tools need when invoked (set on the ninja

modules/toolchain-model/src/triple.cppm

@@ -712,6 +712,27 @@ inline constexpr TargetInfo kKnownTargets[] = {
     // linker and the Apple half of the toolchain model all exist; what is
     // missing is an `os` value and the iPhoneOS SDK.
     //
+    // THE COMPILER IS OURS AND ONLY THE SDK IS APPLE'S, which is the sentence
+    // that shrank this row from a packaging problem to a located directory.
+    //
+    // `llvm@22.1.8` -- any sufficiently new clang emits arm64 Mach-O for an
+    // iOS deployment target, and the C++ runtime comes from the SDK the way it
+    // does on every Apple platform. `aarch64-macos` is verified on exactly
+    // this split and is the precedent: `xim:llvm` compiles and the SDK is
+    // located. Xcode's own clang would also work and is the wrong default --
+    // it would make the compiler a host dependency where the ecosystem
+    // already has one, and these would be the only Apple rows not using
+    // `xim:llvm`.
+    //
+    // A CONVENTION PIN, NOT A CAPABILITY ONE, which is why
+    // `pin_is_capability()` does not name these rows. It means "this is what
+    // `--target aarch64-ios` resolves when the project says nothing", and a
+    // project may still write `[target.aarch64-ios] toolchain = "..."`. The
+    // capability set is the rows NO other payload can serve, and the
+    // distinction matters for consistency with `aarch64-macos`: the same
+    // constraint (Darwin needs clang) holds there and that row is not a
+    // capability row either.
+    //
     // THE SDK IS A LICENCE QUESTION AND NOT A PACKAGING ONE, which is why this
     // row carries no `sysroot`. The NDK is Apache-2.0 and Emscripten is MIT,
     // both redistributable; the iPhoneOS SDK is neither. The recipe should
@@ -725,7 +746,7 @@ 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",   "",    "",           "",                            false },
+    { "aarch64-ios",           "planned",   "",    "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
@@ -743,8 +764,8 @@ inline constexpr TargetInfo kKnownTargets[] = {
     // 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",   "",    "",           "",                            false },
-    { "x86_64-ios-sim",        "planned",   "",    "",           "",                            false },
+    { "aarch64-ios-sim",       "planned",   "",    "llvm@22.1.8","",                            false },
+    { "x86_64-ios-sim",        "planned",   "",    "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