fix(target): every object-format question reads the single answer, and two copies were searching for a vendor name

An audit of the 35 sites that derived the binary format from `os`. Twelve of
them asked "which object format" and were converted to read `object_format()`;
the rest ask a different question -- which payload to install, which loader
variable a platform reads, which flag spelling a compiler wants -- and are
unchanged. The classification mattered more than the count: a site that means
"which OS" and is converted becomes wrong in a new way.

WHAT EACH CONVERTED SITE ANSWERED FOR `aarch64-ios` BEFORE:

    -femulated-tls, -fvisibility-hidden      not passed (Mach-O needs both)
    shared_library_link_flags                $ORIGIN, which ld64 rejects
    shared_soname_flag                       -Wl,-soname, a BFD-only flag
    exports_file_contents / exports_flag     a GNU version script
    debug_info_is_in_band                    true; Mach-O splits to dSYM
    dist::format_for                         the BUILD HOST's format

Every one of those is the ELF branch reached by falling off the end of a
two-valued test, which is the failure `ObjectFormat` was introduced to make
impossible. Verified for every row in `kKnownTargets` that the answer changes
only for `aarch64-ios` and `wasm32-emscripten`, and only toward correctness.

TWO COPIES WERE SEARCHING FOR A VENDOR NAME IN THE WRONG STRING, AND ONE OF
THEM AFFECTS AN ALREADY-VERIFIED ROW.

`compute_flags`'s `linkIntentFlavor` and `resolution.json`'s `format` both
derived the object format by looking for "apple" / "darwin" / "windows" /
"mingw" in `plan.toolchain.targetTriple`. That string is mcpp's CANONICAL
spelling, and `aarch64-macos` contains none of those words. The words live in
the LLVM spelling, which is a different string -- the build report prints both,
either side of an arrow:

    Target aarch64-macos → arm64-apple-macos14.0
           ^ the identity   ^ what clang is given

So an explicit `--target aarch64-macos` linked and recorded as ELF. A NATIVE
macOS build was right by a different branch -- an empty triple reaching the
`needs_explicit_libcxx` rescue -- which is why nothing caught it: two paths
through one function disagreed and only the exercised one was correct. Both now
ask the parsed triple, and the substring test survives only for a spelling
`parse` REJECTS, which is the `[target.<triple>]` escape hatch where an
LLVM-shaped string is what an author actually wrote.

`test_toolchain_triple.cpp` states this as a fact about the vocabulary rather
than as a comment elsewhere: for `aarch64-macos`, `x86_64-macos` and
`aarch64-ios` it asserts the canonical spelling contains neither "apple" nor
"darwin", that the format is Mach-O anyway because it is asked of the fields,
and that the LLVM spelling is where the vendor name lives. A second test takes
its denominator from the table, so a row added without an answer cannot be
covered by a test whose name says every row is.

TWO GAPS ARE NAMED RATHER THAN GUESSED. `dist::Format` and `LinkIntentFlavor`
have no `Wasm` member, so `wasm32-emscripten` still resolves to `Elf` in both.
What "self-contained" and "link_lib" mean for an Emscripten link is a
distribution-contract decision and the open half of #597, not a rename; the
switch names the case so the gap is visible instead of reached by falling
through. `mcpp::pack::run` now refuses a file that is neither ELF, PE nor
Mach-O by name, where it previously handed anything not-PE-not-Mach-O to
`LD_TRACE_LOADED_OBJECTS`.

Docs: the design record's section 3.1 is corrected twice, because two of its
guesses were measured wrong in the same direction -- a vendor had already done
the work and nobody looked. NDK r30 ships the 133-file module surface itself
(r27 shipped none), so for Android there is nothing to derive; and Apple's
libc++ IS a build of a public revision (210106 -> llvmorg-21.1.6), the SDK
ships no surface, and an `import std` Mach-O arm64 binary was linked from a
Linux host. Section 8 names the pattern rather than only listing the facts.

109 unit tests pass.

Author: speak-agent

.agents/docs/2026-09-11-distribution-plugins-and-platform-decomposition.md

@@ -253,10 +253,39 @@ than the shipped state of either toolchain suggests: **`import std` works on
 both Android and Emscripten today, and neither needs a fork or a compiler
 upgrade.** What both need is a directory their vendor chose not to install.
 
-### The gap, stated once
+### The gap, stated once — and closed by one vendor since
 
 An LLVM installation that supports `import std` carries a generated module
-surface beside its headers. Neither vendor ships it:
+surface beside its headers.
+
+**The NDK ships one as of r30.** Measured 2026-09-11 against
+`android-ndk-r30-linux.zip` (`Pkg.Revision 30.0.16248370`, the current LTS):
+`share/libc++/v1/` holds `std.cppm`, `std.compat.cppm`, 110 `std/*.inc` and 21
+`std.compat/*.inc` — the same 133 files this section measured as **absent** on
+r27, generated by Google from the same AOSP checkout as the compiler. So the
+table below is r27's state, and for Android the remedy it describes is no
+longer needed: there is nothing to fetch from an `llvmorg-*` tag, nothing to
+substitute, and no second asset to publish.
+
+Two things about r30 did **not** change, and both matter more than the file
+count:
+
+- **`-D__BIONIC_CTYPE_INLINE=` is still required.** The bionic ctype defect
+  reproduces verbatim on r30 / clang 21: 28 errors, confined to `cctype.inc`
+  and `locale.inc`, `using declaration referring to 'isalnum' with internal
+  linkage cannot be exported`. Google ships the surface without shipping a
+  build of it that works out of the box.
+- **The version to match is still not derivable from the compiler.** r30's
+  `_LIBCPP_VERSION` is `210000` from clang `21.0.0 (based on r574158c)` — an
+  AOSP `toolchains/llvm-project` mirror revision, **not** a build of any public
+  `llvmorg-21.1.x` tag. So the pairing check below cannot compare against an
+  upstream tag for Android; it can only pin the value and refuse a change.
+
+That is the second time a guess in this section was wrong in the same
+direction: **a vendor had already done the work and nobody looked.** The first
+was Apple (below). The table is kept as the r27 measurement it was, because the
+argument it supports — that a target row for a toolchain without the surface
+would be worse than its absence — is what motivated looking at all.
 
 | | `xim:llvm` 20.1.7 | NDK r27 | Emscripten 4.0.19 |
 |---|---|---|---|
@@ -389,14 +418,61 @@ $ node app.js
 half is open: **the standard library story is answered**, and what remains is
 [#597](https://github.com/mcpp-community/mcpp/issues/597)'s target model.
 
-### Apple: not measured, and the recipe may not transfer
+### Apple: measured after all, and every guess in this section was wrong
 
-iOS cannot be measured on a Linux host. Unlike the other two, the remedy may not
-exist: Apple's libc++ is not a build of a public revision, so there is no
-matching `libcxx/modules/` to take a surface from, and the `_LIBCPP_VERSION`
-check that makes the other two recipes safe has nothing to compare against.
-Two honest possibilities, and which holds is a measurement not taken — Xcode's
-toolchain already ships the surface, or iOS waits on Apple.
+This section first said iOS could not be measured on a Linux host, that Apple's
+libc++ is not a build of a public revision, and that the remedy might therefore
+not exist. **All three are false**, measured 2026-09-11 against
+`iPhoneOS26.5.sdk` (49 MB, from a public mirror) and `xim:llvm@22.1.8`:
+
+| | |
+|---|---|
+| `_LIBCPP_VERSION` | **210106** — a public revision, and `llvmorg-21.1.6` exists upstream |
+| `_LIBCPP_ABI_NAMESPACE` | `__1` — upstream's own default, not a vendor-private namespace like the NDK's `__ndk1` |
+| `_LIBCPP_HAS_NO_STD_MODULES` | `/* #undef */` — Apple does **not** disable std modules, unlike the NDK |
+| `std.cppm` in the SDK | **0 files**, exactly as on Android and Emscripten |
+
+So the recipe is the same recipe: take `libcxx/modules/` from the tag matching
+`_LIBCPP_VERSION`, perform the `@LIBCXX_MODULE_STD_INCLUDE_SOURCES@`
+substitution, and get 133 files and 620 KB — the same count and size the other
+two produce, and the same the vendor ships where it ships one at all.
+
+Carried end to end, from a Linux host:
+
+```
+$ clang++ --no-default-config --target=arm64-apple-ios18.0 -isysroot <sdk> \
+      -nostdinc++ -isystem <sdk>/usr/include/c++/v1 -std=c++23 \
+      --precompile surface/std.cppm -o std.pcm        # 34 MB BMI
+$ clang++ ... -fmodule-file=std=std.pcm -c app.cpp    # import std;  OK
+$ clang++ ... -fuse-ld=lld app.o std.pcm -lc++ -o app
+$ file app
+app: Mach-O 64-bit arm64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL|…|PIE>
+```
+
+The binary was not executed — no device and no simulator on a Linux host — so
+this is "compiles and links", which is what the `preview` tier means.
+
+**`--no-default-config` is load-bearing, and the reason generalises past iOS.**
+`xim:llvm`'s payload ships a `bin/clang++.cfg` that injects the host's glibc and
+libc++ unconditionally:
+
+```
+-isystem <xim:llvm>/include/c++/v1
+-isystem <xim:glibc>/include
+-Wl,--dynamic-linker=<xim:glibc>/lib64/ld-linux-x86-64.so.2
+```
+
+Those apply to **every** target the driver is pointed at, so a cross target that
+is not Linux/glibc silently gets the host's C and C++ standard library ahead of
+its own. `-nostdinc++` does not displace them — measured: with `-isysroot` and
+`-nostdinc++` both given, the search list still began with the host's
+`include/c++/v1` and the compile failed inside the host's `stdint.h` on
+`gnu/stubs-32.h`. The criterion is `clang -v`'s search list, not whether the
+compile succeeds, because a compile that reads the wrong standard library
+usually succeeds.
+
+That is a property of the payload rather than of iOS, and it applies to any
+non-Linux target driven through it.
 
 ### What this means for xim-pkgindex
 
@@ -574,14 +650,18 @@ answered it by adding a separate package whose `tests/` selects instead of
 discovering. This is unrelated to plugins and is noted because it is the second
 thing an ecosystem library hits.
 
-**Apple was not measured, and its recipe may not exist.** Android and
-Emscripten were carried to a running or linking artifact; iOS cannot be
-measured on a Linux host, and 3.1 states the two possibilities rather than
-choosing one. The other two results are the argument for not guessing: every
-intermediate guess along the way was wrong — that the gap was one file (it is
-133), that a mismatched surface fails obscurely (it names the missing header),
-that the blocker was libc++ (it was bionic's `static inline` ctype), and that
-Emscripten's libc++ version follows its clang version (it does not).
+**Every guess along the way was wrong, including the ones this document made
+about Apple.** That the gap was one file (it is 133); that a mismatched surface
+fails obscurely (it names the missing header); that the blocker was libc++ (it
+was bionic's `static inline` ctype); that Emscripten's libc++ version follows
+its clang version (it does not); that iOS could not be measured from Linux (it
+can); that Apple's libc++ is not a public revision (it is, 210106); and that
+Xcode might already ship the surface (it does not, and the SDK carries none).
+
+The pattern is worth naming rather than just recording: **each wrong guess was
+about what a vendor had done, and each was cheap to check and was not checked.**
+The section that guessed least — Emscripten, where the version was read rather
+than inferred — is the only one that needed no correction.
 
 **Neither working recipe was carried to a released payload.** Both were built
 and exercised in a scratch directory. Turning each into an xim recipe — the

modules/toolchain-model/src/model.cppm

@@ -497,10 +497,15 @@ std::vector<std::string> graph_runtime_compile_flags(const Toolchain& tc) {
     // defect was invisible until a second architecture was built.
     if (t->arch == "aarch64") out.emplace_back("--rtlib=compiler-rt");
     if (t->is_pe()) out.emplace_back("-fdwarf-exceptions");
-    if (t->is_pe() || t->os == "macos") out.emplace_back("-femulated-tls");
+    // OBJECT FORMAT, NOT OS: `is_mach_o()` covers iOS along with macOS, which
+    // `os == "macos"` used to miss. Both need the emulated-TLS model for the
+    // same reason PE does -- `_tlv_bootstrap` is loader-bootstrapped there
+    // exactly as `_tls_index` is on PE.
+    if (t->is_pe() || t->is_mach_o()) out.emplace_back("-femulated-tls");
     // MACH-O ONLY, AND THE REASON IS THAT WEAK-DEF IS A RUN-TIME MECHANISM
-    // THERE. See the note on this function for the measurement.
-    if (t->os == "macos") {
+    // THERE. See the note on this function for the measurement. `is_mach_o()`
+    // rather than `os == "macos"`: the mechanism is ld64's, which iOS shares.
+    if (t->is_mach_o()) {
         out.emplace_back("-fvisibility=hidden");
         out.emplace_back("-fvisibility-inlines-hidden");
     }
@@ -524,8 +529,11 @@ bool target_supports_full_static(std::string_view targetTriple, bool hostCapabil
     // false is what keeps the two mechanisms from both emitting the flag.
     if (t->is_pe()) return false;
 
-    // macOS cannot fully static-link: libSystem must stay dynamic.
-    if (t->os == "macos") return false;
+    // Mach-O cannot fully static-link: libSystem (macOS) / the Apple
+    // equivalent (iOS) must stay dynamic. `is_mach_o()`, paired with `is_pe()`
+    // above, so this reads as "for each object format" rather than leaving
+    // iOS to fall through to the `linux` line below by accident.
+    if (t->is_mach_o()) return false;
 
     // Linux ELF — glibc or musl, native or cross. This is the line that was
     // previously gated on the HOST being Linux.

src/build/distribution.cppm

@@ -129,9 +129,22 @@ enum class Format { Elf, MachO, Pe };
 Format format_for(std::string_view targetTriple, Format hostFallback) {
     if (auto parsed = mcpp::toolchain::triple::parse(targetTriple)) {
         if (parsed->is_pe())         return Format::Pe;
-        if (parsed->os == "macos")   return Format::MachO;
+        // `is_mach_o()`, not `os == "macos"`: the latter answered the
+        // opposite-hosts defect above for macOS and would still get iOS
+        // wrong the same way, since iOS's `os` is `ios`.
+        if (parsed->is_mach_o())     return Format::MachO;
         if (parsed->os == "linux"
             || parsed->os == "none") return Format::Elf;
+        // THIS `Format` HAS NO FOURTH MEMBER YET. A wasm32-emscripten
+        // triple parses here and falls out of every branch above (`is_pe()`
+        // and `is_mach_o()` are both false, and its `os` is `emscripten`,
+        // neither `linux` nor `none`) to the substring fallback below, which
+        // also does not name it, and then to `hostFallback` -- so today this
+        // function still answers the machine's own format for wasm rather
+        // than the target's, the same defect class its own header measured
+        // for macOS. Adding `Format::Wasm` is deferred to whoever gives this
+        // module a Mach-O-shaped mechanism for it (see `resolve`'s `switch`),
+        // not attempted here.
     }
     if (targetTriple.find("windows") != std::string_view::npos
         || targetTriple.find("mingw") != std::string_view::npos)

src/build/flags.cppm

@@ -691,6 +691,40 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     const auto linkIntentFlavor = [&] {
         if (isMingwTc) return LinkIntentFlavor::PeGnu;
         if (isMsvcDialect) return LinkIntentFlavor::PeMsvc;
+        // THE OBJECT FORMAT IS ASKED OF THE PARSED TRIPLE, AND THE SUBSTRING
+        // TEST BELOW IS NOW ONLY THE ESCAPE HATCH.
+        //
+        // `plan.toolchain.targetTriple` is mcpp's CANONICAL spelling, and
+        // `aarch64-macos` contains neither "apple" nor "darwin" -- so an
+        // explicit `--target aarch64-macos`, a verified row, fell through to
+        // `Elf`. Only a NATIVE macOS build was right, and by a different
+        // branch: an empty triple reaching the `needs_explicit_libcxx` rescue
+        // below. That is why nothing caught it -- the two paths through this
+        // function disagreed and only one of them was exercised.
+        //
+        // The substring test is kept for a triple `parse` REJECTS, which is
+        // the `[target.<triple>]` escape hatch: an author may name a spelling
+        // outside the canonical vocabulary, and it is then an LLVM-shaped
+        // string where "apple" and "windows" do appear.
+        if (auto t = mcpp::toolchain::triple::parse(plan.toolchain.targetTriple)) {
+            switch (t->object_format()) {
+                case mcpp::toolchain::triple::ObjectFormat::MachO:
+                    return LinkIntentFlavor::MachO;
+                case mcpp::toolchain::triple::ObjectFormat::Pe:
+                    return LinkIntentFlavor::PeGnu;
+                case mcpp::toolchain::triple::ObjectFormat::Wasm:
+                    // No `LinkIntentFlavor::Wasm` exists, and inventing one
+                    // here would be a link-contract decision rather than a
+                    // format question -- what `link_lib` and a search path
+                    // even mean for an Emscripten link is the open half of
+                    // #597. `Elf` is the wrong answer and is the one this
+                    // returns; it is named here so the gap is visible rather
+                    // than reached by falling off the end of a switch.
+                    return LinkIntentFlavor::Elf;
+                case mcpp::toolchain::triple::ObjectFormat::Elf:
+                    return LinkIntentFlavor::Elf;
+            }
+        }
         auto triple = plan.toolchain.targetTriple;
         std::ranges::transform(triple, triple.begin(),
             [](unsigned char c) { return std::tolower(c); });

src/build/ninja_backend.cppm

@@ -260,15 +260,18 @@ std::string pe_link_flag(const BuildPlan& plan, bool sep,
 std::string shared_soname_flag(const LinkUnit& lu, const BuildPlan& plan) {
     if (lu.kind != LinkUnit::SharedLibrary) return "";
     const auto t = mcpp::toolchain::triple::parse(plan.toolchain.targetTriple);
-    const std::string os = t ? t->os
-        : (mcpp::platform::is_macos   ? "macos"
-         : mcpp::platform::is_windows ? "windows" : "linux");
+    // WHICH FLAG SPELLING, ASKED OF THE OBJECT FORMAT DIRECTLY rather than of
+    // an `os` string: the prior `os == "macos"` fell through to the ELF
+    // branch (`-Wl,-soname`, a GNU ld/BFD flag ld64 does not accept) for
+    // iOS, whose `os` is `ios`.
+    const bool pe    = t ? t->is_pe()     : bool(mcpp::platform::is_windows);
+    const bool macho = t ? t->is_mach_o() : bool(mcpp::platform::is_macos);
     // PE records no such name: a DLL is found by the filename in the importing
     // module's import table, and there is nothing to override.
-    if (os == "windows") return "";
+    if (pe) return "";
     const std::string name = lu.soname.empty()
         ? lu.output.filename().string() : lu.soname;
-    if (os == "macos") return "-Wl,-install_name,@rpath/" + name;
+    if (macho) return "-Wl,-install_name,@rpath/" + name;
     return lu.soname.empty() ? "" : "-Wl,-soname," + lu.soname;
 }
 
@@ -291,7 +294,11 @@ std::string shared_soname_flag(const LinkUnit& lu, const BuildPlan& plan) {
 // script's syntax is not what the author wrote.
 std::string exports_file_contents(const LinkUnit& lu, std::string_view os) {
     std::string out;
-    if (os == "macos") {
+    // Which SYMBOL-TABLE SYNTAX, which is a property of the object format:
+    // iOS links with the same ld64 and the same leading-underscore Mach-O
+    // symbol table as macOS, so it takes this branch too rather than the
+    // GNU version-script one below, which ld64 does not parse.
+    if (os == "macos" || os == "ios") {
         // One symbol per line. Mach-O symbols carry a leading underscore that
         // the C++ source never writes, so it is added here -- the author names
         // the symbol, not the object format's spelling of it.
@@ -316,7 +323,10 @@ std::string exports_flag(const LinkUnit& lu, std::string_view os,
                          const std::filesystem::path& file) {
     if (lu.kind != LinkUnit::SharedLibrary || lu.exportPatterns.empty()) return "";
     if (os == "windows") return "";
-    if (os == "macos")
+    // iOS alongside macOS, matching `exports_file_contents`: same linker,
+    // same flag. Leaving it out sent an iOS shared-library link a GNU
+    // `--version-script` for a Mach-O symbol list, which ld64 rejects.
+    if (os == "macos" || os == "ios")
         return "-Wl,-exported_symbols_list," + file.generic_string();
     return "-Wl,--version-script=" + file.generic_string();
 }

src/build/plan.cppm

@@ -555,8 +555,12 @@ std::vector<std::string> shared_library_link_flags(
     const mcpp::toolchain::triple::Triple& target) {
     std::vector<std::string> flags;
     const bool pe    = n.sharedNeedsImportLib;
+    // WHICH RPATH SYNTAX, ASKED OF THE OBJECT FORMAT. `target.os == "macos"`
+    // used to answer this and missed iOS, which links with the same ld64 and
+    // wants the same `@loader_path` -- `os == "ios"` would otherwise take the
+    // ELF branch below and hand `$ORIGIN` to a linker that has no such token.
     const bool macho = target.empty() ? bool(mcpp::platform::is_macos)
-                                      : target.os == "macos";
+                                      : target.is_mach_o();
     if (pe) {
         flags.push_back(import_library_for(t, n).generic_string());
     } else {
@@ -810,9 +814,16 @@ std::vector<mcpp::platform::search::Dir> runtime_search_closure(
         auto t = mcpp::toolchain::triple::parse(plan.toolchain.targetTriple);
         return t ? *t : mcpp::toolchain::triple::Triple{};
     }();
+    // `!= "macos" && != "windows"` READ AS "ELF" BY EXCLUSION, WHICH IS THE
+    // ONE ANSWER THAT MUST NEVER BE REACHED BY EXCLUDING EVERYTHING ELSE:
+    // iOS and wasm32-emscripten both satisfy that double negative (their `os`
+    // is `ios` / `emscripten`, neither string), so this line called an iOS
+    // Mach-O and a wasm module ELF and would have handed both a DT_RPATH
+    // mechanism neither format has. Asked of `object_format()` directly, the
+    // single derivation, instead.
     const bool elfTarget = triple.empty()
         ? bool(mcpp::platform::is_linux)
-        : (triple.os != "macos" && triple.os != "windows");
+        : (triple.object_format() == mcpp::toolchain::triple::ObjectFormat::Elf);
 
     // THE ARTIFACT'S OWN DIRECTORY — `$ORIGIN` (#415).
     //
@@ -1059,10 +1070,13 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
 
     // The loader-tag contract exists only where DT_RPATH/DT_RUNPATH do.
     // Mach-O and PE have neither, so they get no flag rather than a branch in
-    // every consumer.
+    // every consumer. Asked of `object_format()`: the exclusion form this
+    // used to be (`!= "macos" && != "windows"`) answers "ELF" for any `os` it
+    // does not name, which is wrong the same way for iOS and for
+    // wasm32-emscripten — see the sibling derivation earlier in this file.
     const bool elfTarget = targetTriple.empty()
         ? bool(mcpp::platform::is_linux)
-        : (targetTriple.os != "macos" && targetTriple.os != "windows");
+        : (targetTriple.object_format() == mcpp::toolchain::triple::ObjectFormat::Elf);
     auto loader_tag_flag = [&](LinkUnit::Kind kind) -> std::string {
         if (!elfTarget) return {};
         using mcpp::build::loader::Form;