feat(toolchain): a spec that names a payload has answered which payload, and the iOS rows are written down

NEITHER `mcpp toolchain install emsdk` NOR `mcpp toolchain install android-ndk`
HAD EVER WORKED, and openkal-emscripten's continuous integration is what found
it:

  $ mcpp toolchain install emsdk 6.0.9
    error: installed package has no known C++ frontend in
           '.../xim-x-emsdk/6.0.9/bin'

TWO DEFECTS, ONE PER AXIS.

`to_xim_package` decided the payload from the TARGET. That is right for the
spelling a build uses -- `--target wasm32-emscripten` with nothing declared --
and there is no target at all in an install, so the emsdk spec resolved the
generic llvm shape and looked for `clang++` in `bin/` while `em++` is in
`emscripten/`. `payloadName` is the field `parse_toolchain_spec` fills from the
spelling and is the more direct statement of the two: a spec that names a
payload has answered this question. It decides first; the target remains the
answer for a spec that names no payload, which is the escape-hatch spelling the
capability gate has to be able to refuse.

And the install path composed `<root>/bin` itself. That was one of the five
sites the `frontendSubdir` note in mcpp.toolchain.registry records; four were
repaired and this one was not. It now asks `payload_frontend`, which is the
same function the build path asks -- so the two cannot disagree, and the
install picks up the payload's descriptor for free.

AND THE FIXTURE OF THE TEST THAT COVERS THIS AXIS HAD PICKED ITS OBJECT BY
CONVENIENCE. `TheTargetChoosesThePackageAndThePackageKnowsItsLayout` built
every case from `emsdk@6.0.9` and replaced only the target, which worked while
the target was the only thing read. It now builds them from `llvm@22.1.8`,
which names the family and no payload -- the shape whose resolution that test
exists to state.

D5. THE iOS ROWS ARE WRITTEN DOWN, in docs/20 and its Chinese copy: the
compiler is ours and only the SDK is Apple's, the two host dependencies this
platform adds are named and bounded, the deployment target travels in the
effective triple alone, and the simulator is two rows because it runs the
host's architecture.

`examples/13-platform-targets` gains the iOS rows with measured readings --
`platform 2` for the device and `platform 7` for the simulator, which is the
one pair a successful build cannot tell apart -- and records two limitations it
ran into rather than working around them: `deps` is not conditional on a
target, and `xim:apple-simulator-tools` exists for macosx alone, so declaring
the runner's package in the manifest would make this example's Linux build
depend on a macOS-only package. The program is installed by whoever runs those
rows.

E4c. `docs/24-openkal-cross` and its Chinese copy stop saying the Web needs an
implementation and name `openkal-emscripten`, with the three-group table that
makes a partial surface a conformant one. The iOS section stops being a
structural argument: what the SDK's licence bounds is packaging it, not
locating it, and `aarch64-macos` has been verified on exactly that split since
before these rows existed.

e2e 641 gains the iOS claims that a non-Apple host can make: the rows name
their payload, and the SDK's absence is a refusal that names the SDK, the
`xcrun` command, the Command-Line-Tools note and the compiler -- arriving
before any payload is resolved. The effective-triple claim is a unit test
instead, because that same gate means a host without Xcode never prints the
line an end-to-end check would read.

AND THE macOS LEG NOW RUNS THE ARTEFACT THROUGH THE SUPPORTED PATH. The
earlier leg spawned it by hand, which proves the platform can run it and not
that mcpp can; `mcpp run --target aarch64-ios-sim` goes through the `runner`
the manifest declares and the program `xim:apple-simulator-tools` provides.

Author: speak-agent

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

@@ -263,6 +263,31 @@ jobs:
 
           [target.x86_64-ios-sim]
           toolchain = "llvm@22.1.8"
+
+          # D4: THE RUNNER IS AN ARGV PREFIX AND THE SESSION BELONGS TO A
+          # PACKAGE. `simctl-run` comes from `xim:apple-simulator-tools`; it
+          # chooses a device, boots it if it is not booted, waits, spawns, and
+          # returns the program's own exit status. The engine learns nothing
+          # about simulators, which is the boundary it keeps for every other
+          # emulated target.
+          #
+          # The device row keeps `runner` unset: an artefact cannot be run off
+          # an iOS device without a signature the developer owns.
+          #
+          # THE TOOL IS DECLARED AT THE TOP LEVEL HERE AND NOT IN
+          # examples/13, and the difference is which hosts the manifest has to
+          # work on. `deps` is not conditional on a target -- measured:
+          # "[target.aarch64-ios-sim.xlings] does not accept 'deps'" -- and
+          # `xim:apple-simulator-tools` exists for macosx alone, so an
+          # unconditional declaration breaks a Linux build. This fixture is
+          # macOS-only, so it can say it.
+          [xlings]
+          deps = ["xim:apple-simulator-tools"]
+          TOML
+          cat >> /tmp/iostest/mcpp.toml << 'TOML'
+
+          [target.aarch64-ios-sim]
+          runner = ["simctl-run"]
           TOML
           cat > /tmp/iostest/src/main.cpp << 'CPP'
           import std;
@@ -319,21 +344,72 @@ jobs:
             echo "SPAWN-FAILED exit=$?"
           fi
 
+      # D4: `mcpp run` THROUGH THE RUNNER, WHICH IS THE SUPPORTED PATH.
+      #
+      # The step above spawned the artefact by hand, which proves the platform
+      # can run it and not that mcpp can. 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 is a `runner`
+      # a manifest declares and a program a package provides.
+      - name: "D4: mcpp run --target aarch64-ios-sim prints 1-2-3"
+        continue-on-error: true
+        run: |
+          set -x
+          cd /tmp/iostest
+          out=$("$MCPP_DEV" run --target aarch64-ios-sim 2>&1) || true
+          set +x
+          printf '%s\n' "$out" | tail -20
+          if printf '%s\n' "$out" | grep -q '1-2-3'; then
+            echo "RUN-THROUGH-RUNNER-OK"
+          else
+            echo "RUN-THROUGH-RUNNER-FAILED"
+          fi
+
+      # x86_64-ios-sim IS THE THIRD ROW AND THIS RUNNER CANNOT RUN IT.
+      #
+      # The simulator runs the HOST's architecture, so an Apple-silicon machine
+      # has no x86_64 iOS runtime to spawn into. What can be measured here is
+      # the ARTEFACT, which is the claim the row's tier will rest on; a machine
+      # with an Intel host is what would move it further.
+      - name: "x86_64-ios-sim: the artefact, on a host that cannot run it"
+        continue-on-error: true
+        run: |
+          set -x
+          cd /tmp/iostest
+          "$MCPP_DEV" build --target x86_64-ios-sim
+          set +x
+          ART=$(find /tmp/iostest/target/x86_64-ios-sim -name iostest -type f | head -1)
+          file "$ART"
+          otool -l "$ART" | grep -A5 LC_BUILD_VERSION
+
       # 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"
+      # AND NOT BY POINTING `DEVELOPER_DIR` AT NOTHING, WHICH MEASURED NOTHING.
+      #
+      # The first version of this step set `DEVELOPER_DIR=/nonexistent` and
+      # expected the refusal. The build SUCCEEDED: `xcrun` ignores an invalid
+      # developer directory and falls back to the recorded one, so the
+      # environment change did not make the SDK unlocatable. The predicate was
+      # right and the object was wrong -- the claim was never tested.
+      #
+      # The claim now lives where the SDK is genuinely absent, which is every
+      # non-Apple host: `tests/e2e/641` asserts it on Linux and Windows, with
+      # an explicit toolchain override so the tier gate does not answer first
+      # and `MCPP_NO_AUTO_INSTALL=1` so no payload is needed. What is left for
+      # this runner is the other half of the same claim -- that a machine which
+      # DOES have the SDK is not refused -- and that is what the steps above
+      # measure by building.
+      - name: "D: the SDK is located here, which is the other half of the claim"
         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
+          xcrun --sdk iphoneos --show-sdk-path
+          xcrun --sdk iphonesimulator --show-sdk-path
           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
+          echo "both SDKs located; the refusal for a machine without them is"
+          echo "asserted by tests/e2e/641 on every non-Apple host"
+          cd /tmp/iostest && "$MCPP_DEV" build --target aarch64-ios 2>&1 | tail -3

docs/20-toolchains.md

@@ -595,8 +595,105 @@ an argv prefix and the session belongs to a package rather than to the engine:
 ```toml
 [target.x86_64-linux-android]
 runner = ["adb-run"]             # a program from xim:android-platform-tools
+
+[target.aarch64-ios-sim]
+runner = ["simctl-run"]          # a program from xim:apple-simulator-tools
 ```
 
+A runner is an argv prefix and a *session* is not. Running a program on an iOS
+simulator means choosing a device, booting it if it is not booted, waiting for
+the boot, spawning, and returning the program's own exit status; a manifest
+line has no beginning and no end, which is why that work lives in a package.
+
+## The Apple SDKs Are Located, Not Installed
+
+The three iOS rows -- `aarch64-ios`, `aarch64-ios-sim` and `x86_64-ios-sim` --
+are the other shape a platform can take, and they are worth reading beside the
+two SDK toolchains above because they answer the same question differently.
+
+**The compiler is ours; only the SDK is Apple's.** Any sufficiently new clang
+emits arm64 Mach-O for an iOS deployment target, so these rows pin
+`llvm@22.1.8` -- the ordinary payload, the same one `aarch64-macos` uses. What
+cannot be packaged is the iPhoneOS and iPhoneSimulator SDK: it ships inside
+Xcode and is not redistributable. So mcpp **locates** it, through
+`xcrun --sdk <name> --show-sdk-path`, exactly as it has always located the
+macOS SDK.
+
+That is why these rows carry no `sysroot` entry. That column names a package,
+and a located directory is not one.
+
+```bash
+mcpp build --target aarch64-ios        # resolves llvm@22.1.8 + the iPhoneOS SDK
+mcpp build --target aarch64-ios-sim    # resolves llvm@22.1.8 + the Simulator SDK
+```
+
+### The host surface this adds, named and bounded
+
+Two items, both macOS-only, both in the category a proprietary runtime that
+exists only on its own operating system occupies:
+
+| the item | reached through | the permission |
+|---|---|---|
+| the iPhoneOS / iPhoneSimulator SDK | `xcrun` | not redistributable; there is nothing to package |
+| the simulator runtime | `simctl`, via `xim:apple-simulator-tools` | the same |
+
+Everything else is ecosystem: the compiler, the C++ runtime, the linker and the
+packaging. Neither item is reached by a fallthrough -- each is asked for
+deliberately, and its absence is a refusal that names it:
+
+```
+error: target aarch64-ios needs the iphoneos SDK, which this machine does not provide.
+       It is not redistributable, so mcpp LOCATES it rather than installing it:
+       `xcrun --sdk iphoneos --show-sdk-path` must answer, which needs Xcode on
+       macOS (not the Command Line Tools alone -- those ship the macOS SDK only).
+       Check `xcode-select -p`, and note that the compiler is not what is
+       missing: these rows pin `xim:llvm`, which every other Apple row also uses.
+```
+
+The refusal arrives **before** any payload is resolved. An Apple SDK is not
+something a dependency can supply, so there is nothing a later step could learn
+that would change the answer -- and a machine without Xcode should not download
+a compiler before being told the compiler is not what is missing.
+
+### The deployment target
+
+`[build] ios_deployment_target` sits beside `macos_deployment_target`, and the
+two are separate keys for one reason: `"14.0"` is a macOS version and means
+nothing to an iOS SDK. Only one of them can apply to any given target, so they
+share a single slot in the build fingerprint.
+
+```toml
+[build]
+ios_deployment_target = "18.0"
+```
+
+It is carried by the **effective triple** and nowhere else:
+
+```
+Target aarch64-ios     → arm64-apple-ios18.0
+Target aarch64-ios-sim → arm64-apple-ios18.0-simulator
+```
+
+which are Apple's own spellings. No `-miphoneos-version-min` flag is emitted:
+the triple fully determines the platform and the minimum, and a flag would be a
+second place answering a question the triple already answers. Leaving the key
+unset is legal and means the SDK's own default, which clang supplies for an
+Apple target -- unlike Android, where bionic refuses an unversioned triple
+outright.
+
+### The simulator's shape, and its boundary
+
+The simulator is two rows and not a flag on the device row. A simulator build
+has its own SDK, produces an object naming its own platform
+(`LC_BUILD_VERSION` reports `IOSSIMULATOR` rather than `IOS`), and takes a
+different deployment-target segment. Both architectures exist because the
+simulator runs the **host's** architecture: an Apple-silicon machine needs
+`aarch64-ios-sim` and an Intel one needs `x86_64-ios-sim`.
+
+The device row keeps `runner` unset. An artifact cannot be run off an iOS
+device without a signature the developer owns, which is not something a build
+tool can supply.
+
 ## Project-Level Version Pinning
 
 If a project needs to pin a specific version rather than rely on the global default, declare it in the project's `mcpp.toml`:

docs/24-openkal-cross.md

@@ -225,32 +225,83 @@ openkal: 1-2-3          exit 0
 is the weaker claim of the two and is worth stating separately: the first says
 the implementation builds, the second says a program over it runs.
 
-### iOS would share the macOS implementation, and that cannot be claimed yet
-
-The same argument applies on Apple's side — iOS and macOS share the Darwin
-kernel, and `openkal-macos` is arch-dispatched the same way — but the argument
-is not evidence. The iPhoneOS and iPhoneSimulator SDKs ship inside Xcode and
-are not redistributable, so the `aarch64-ios` and `*-ios-sim` rows are
-`planned`: there is nothing to build against and therefore nothing to run.
-Declaring support on a structural argument alone is the shape this ecosystem has
-paid for before — a package present in an index is not a package that builds a
-real project — so these rows claim nothing until an SDK is reachable.
-
-### Web needs a new implementation, and a different one
+### iOS shares the macOS implementation, and the SDK is located rather than packaged
+
+The same argument applies on Apple's side: iOS and macOS share the Darwin
+kernel, the same call numbers and the same calling convention, and
+`openkal-macos` is arch-dispatched the same way. What differs between them is
+the SDK and the deployment-target flag, and both belong to the build tool
+rather than to the implementation — so iOS is one `cfg` line in a manifest and
+no new package.
+
+**What was blocked was the SDK, and what unblocked it was asking a smaller
+question.** The iPhoneOS and iPhoneSimulator SDKs ship inside Xcode and are not
+redistributable, which bounds *packaging* them. It does not bound *locating*
+them: `aarch64-macos` has been `verified` on exactly that split since long
+before these rows existed — `xim:llvm` compiles and the machine's macOS SDK is
+found through `xcrun`. The iOS rows take the same split with a second SDK, so
+they pin `llvm@22.1.8` and carry no `sysroot` entry, because that column names a
+package and a located directory is not one.
+
+The consequence for this document is that the rows are no longer a structural
+argument. `openkal-macos` compiles for them, and what a reader needs to know is
+that the SDK is a named host dependency — one of exactly two this platform adds,
+the other being `simctl` — and that its absence is a refusal naming the SDK
+rather than a build that quietly produces a macOS artefact.
+
+### Web needed a new implementation, and `openkal-emscripten` is it
 
 Emscripten is the one of the three that changes the model rather than extending
 it. There is no kernel and there are no system calls to issue: Emscripten
 supplies its own C library over a JavaScript host. An openkal implementation for
 it therefore cannot be written the way `openkal-linux` is — beneath a C library
-— and would have to sit **above** one. The specification permits exactly that
-("an implementation may be built upon a C library, beneath one, or without
-one"), so this is new software rather than a sharing decision, and it is the one
-of the three that is neither done nor blocked.
+— and has to sit **above** one. The specification permits exactly that ("an
+implementation may be built upon a C library, beneath one, or without one"), so
+this was new software rather than a sharing decision.
+
+`openkal-emscripten` is the first implementation in this ecosystem written in
+that direction. That makes the code thin and not easy: a forward and an error
+translation is most of each function, and what it has to get right is the
+places where the C library's vocabulary and openkal's do **not** correspond —
+the granularity that is an alignment and not a page, a monotonic clock whose
+resolution a browser deliberately coarsens, a terminal that exists under node
+and not in a page.
+
+**A partial surface is a conforming one, and the specification says how.**
+Clause 6.2 gives three times, each the earliest at which the information
+exists, and the implementation's three groups get three different treatments:
+
+| group | treatment | the reason |
+|---|---|---|
+| `stream`, `fs`, `time`, `env`, `memory`, `random`, `abort`, `terminal` | provided, forwarding to Emscripten's libc | MEMFS and the JavaScript host serve all of these |
+| `net`, `datagram`, `timeout` | provided, with the capability word reporting what is exercisable | the calls are real and the transport is a WebSocket proxy, so `kal_net_props` claims neither IPv6 nor half-close |
+| `process`, `exec`, `space` | NOT PROVIDED | there is no fork, no exec and no second address space |
+
+The third row is the decision worth stating plainly: **an absent symbol is the
+report.** Measured:
+
+```
+wasm-ld: error: obj/main.o: undefined symbol: kal_process_spawn
+```
 
-Until it exists, `wasm32-emscripten` is served the ordinary way: by a payload.
-`xim:emsdk` ships the compiler, the sysroot and a libc++ module surface, so a
-program that uses `import std` builds and runs for the Web today without openkal
-being involved at all — which is what the row's `verified` tier records.
+which is clause 6.2's second time. Providing `kal_process_spawn` so that it
+returned an error would be the shape the specification forbids — present and
+always failing, which the caller cannot tell from a condition — and it would
+move a fact known at link time to run time.
+
+`openkal.task` is carried by a feature for a reason specific to this platform:
+threads need `-pthread`, which selects a different C library build, a different
+memory model and a different loader contract. Without the feature the
+translation unit is empty and the eight symbols do not exist, which is the same
+treatment the three absent interfaces get. With it they do, and
+`kal_interfaces()` follows the link rather than a name the package invented.
+
+None of this replaces the payload route. `wasm32-emscripten` is still served
+the ordinary way — `xim:emsdk` ships the compiler, the sysroot and a libc++
+module surface, so a program that uses `import std` builds and runs for the Web
+with openkal not involved at all, which is what the row's `verified` tier
+records. openkal is what a program uses when it wants one source above several
+platform interfaces.
 
 ### The table
 
@@ -259,9 +310,9 @@ being involved at all — which is what the row's `verified` tier records.
 | Linux (glibc, musl) | `openkal-linux` | the reference implementation |
 | Android (both ABIs) | `openkal-linux`, unchanged | builds; a program over it ran on an emulator |
 | macOS | `openkal-macos` | on the macOS system-call surface |
-| iOS, iOS simulator | `openkal-macos` would serve it | blocked: the SDK is not redistributable |
+| iOS, iOS simulator | `openkal-macos`, unchanged | Darwin is Darwin; the SDK is located, not packaged |
 | Windows | `openkal-windows` | on Win32 and the object manager |
-| Web (Emscripten) | none | needs an implementation written ABOVE a C library |
+| Web (Emscripten) | `openkal-emscripten` | written ABOVE a C library; twelve of fifteen interfaces |
 
 ## Bare Metal