feat(target): Android, iOS and wasm are rows, and the object format is an axis

Section 3 of the design record draws the boundary exactly: a package can add a
language, a tool, an action, a payload and a generated module, and IT CANNOT ADD
A TRIPLE. Identity is three strings and `kKnownTargets` is compiled into the
binary, so every layer below the first -- the `.apk` step, the `.app` step, the
`.html`+`.wasm` step, the runner, the signing, the non-C++ glue -- waits on a
row here and on nothing else in the engine. Registering the rows is what turns
each of those from a plugin with nowhere to attach into a plugin that can be
written.

    aarch64-linux-android   x86_64-linux-android   aarch64-ios   wasm32-emscripten

ALL FOUR ARE `planned`, WHICH IS A REFUSAL AND NOT A GAP. The tier gate answers
`tier-planned` naming the row:

    error: target 'aarch64-linux-android' is registered but not yet supported
           (planned) -- no toolchain is published for it yet
    error: target 'aarch64-linux-androideabi' (which resolves to
           'aarch64-linux-android') is registered but not yet supported

rather than `unknown target`, which was false, or a build that resolves and
produces nothing, which section 3.1 argues would be worse than the row's
absence. What each row still needs is a PAYLOAD in every case and never engine
work: `xim:android-ndk`, `xim:emsdk`, and for iOS a licence reading before a
packaging decision.

THE OBJECT FORMAT IS NOW ONE ANSWER, AND THAT IS WHAT #597 ACTUALLY NEEDED.

The binary format was never a field. It was re-derived from `os` wherever it was
needed -- `is_pe()` asked `os == "windows"`, artifact naming asked again, the
packer asked a third time -- which is affordable only while the answer has two
values. `wasm32` is the first target in mcpp's vocabulary whose format is
neither, and a THIRD value turns those derivations into an addition at every
such site. A site that is missed does not fail: it silently answers ELF,
because ELF is what every `else` branch in the tree assumes. `ObjectFormat` is
that addition made once, with `is_pe()` / `is_mach_o()` / `is_wasm()` reading it.

It is deliberately NOT the same question as `is_freestanding()`. A bare-metal
RISC-V image is ELF with no OS; a wasm module has an OS-like layer
(Emscripten's POSIX emulation) and is not ELF. Merging the two axes is the
mistake this replaces.

ANDROID'S PLACEMENT IS THE MODELLING DECISION: `env = "android"` on a `linux`
OS, not `os = "android"`. The kernel IS Linux, so ELF, the `unix` family and
`nasm -f elf64` are already right; an OS value would have made every one of
them wrong by default and required a new answer at each site. What differs from
`gnu` is bionic, the loader path and the SDK -- which is what an `env` value is
for. `androideabi` resolves to the same env: the EABI half is the ARM calling
convention, which the arch segment already carries.

`is_apple()` exists because a site that means "Apple" and asks "macOS" gets iOS
wrong in the direction that still links. iOS shares the object format, the
linker, the `arm64` spelling and `codesign` with macOS, and differs in the SDK
and the deployment-target flag. No deployment target is baked into
`llvm_triple()` for it, unlike the macOS branch: `-miphoneos-version-min`
belongs to the layer that owns the SDK and the bundle, and a default here would
be a second place that answers it.

A DISPLAY DEFECT THE ROWS EXPOSED. `x86_64-linux-android` showed no `cross` tag,
because that test compared arch and OS only -- and this target agrees with an
x86_64 Linux host on both. An Android artifact needs bionic's loader at
`/system/bin/linker64`, which no ordinary Linux host has, so it cannot run
there. Spelled as a property rather than by adding `env != env`, which would
have taken `x86_64-linux-musl` with it -- that one is static and does run here.

48 new cells in tests/matrix/expected.tsv, one per (mode, host, compiler) the
table declares, all `unsupported / tier-planned`; the declared per-host counts
move with them, because compare.sh checks the total before it checks a cell.
The day a row is wired, its cells go red and say so. Verified locally:
50/50 payload and 24/24 graph on linux-x86_64.

Docs: `docs/21`'s segment tables gain the new values, a section states the
object-format axis and why it is not the freestanding question, and the
host/target matrix gains four rows. Both READMEs' platform tables record what
each row waits on. Both languages.

Author: speak-agent

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

@@ -710,24 +710,59 @@ requests **no** format and asserts the set is still non-empty.
 | A dist member's tool is absent | The tool is a host lookup, and an empty path becomes an argv token | Refuse in the build program, naming the tool and where it was looked for |
 | The produced distributable is valid and empty | Section 2's measured 52 KB installer | Each member asserts a floor on its own output, on the **success** path, through `mcpp::warning` |
 
-### 9.7 What sections 4 to 7 promise that this pass does not deliver
-
-Stated here rather than discovered later. Each is blocked on something no
-amount of engine work supplies:
-
-- **`xim:android-ndk`, `xim:emsdk`** (§7 step 5) and the **Android row**
-  (step 6). Both recipes are measured working in a scratch directory (§3.1);
-  turning either into a payload means fetching and republishing a
-  multi-gigabyte vendor toolchain with a derived 133-file module surface. That
-  is its own release, not a side effect of this one.
-- **The iOS row** (step 7) and `dist-apple`'s iOS half. Not measurable on a
-  Linux host, and §3.1 states the two possibilities rather than choosing.
-- **Web** (step 8). [#597](https://github.com/mcpp-community/mcpp/issues/597)
-  is a target-model change.
-- **`dist-android`, `dist-web`**. Each waits on its row.
-
-The engine additions in §2.2 are what make each of those a single verifiable
-change when it comes. None of them is a prerequisite for the others.
+### 9.7 The engine's half of section 3, and what is left after it
+
+Section 3's boundary is exact: a package can add a language, a tool, an action,
+a payload and a generated module, and it **cannot add a triple**. Every layer
+below the first — the `.apk` step, the `.app` step, the `.html`+`.wasm` step,
+the runner, the signing, the non-C++ glue — therefore waits on a row in
+`kKnownTargets` and on nothing else in the engine. So the rows are engine work
+and belong in the same release as §2.2:
+
+| Row | Tier | What it still needs |
+|---|---|---|
+| `aarch64-linux-android`, `x86_64-linux-android` | `planned` | `xim:android-ndk` |
+| `aarch64-ios` | `planned` | the iPhoneOS SDK, and a licence reading first (§9.8) |
+| `wasm32-emscripten` | `planned` | `xim:emsdk` |
+
+**`planned` is a refusal, not a gap.** The tier gate answers `tier-planned`
+naming the row, so `mcpp build --target aarch64-linux-android` says the
+vocabulary has this target and nothing is wired yet — rather than `unknown
+target`, which was false, or a build that resolves and produces nothing, which
+§3.1 argues would be worse than the row's absence. Each cell is declared in
+`tests/matrix/expected.tsv`, so the day a row is wired the matrix goes red and
+says so.
+
+**Web needed one thing the other two did not, and it was not a table row.** The
+binary format was never a field: it was re-derived from `os` at each site that
+needed it, which is affordable while the answer has two values. `wasm32` is the
+first target whose format is neither, and a third value turns those derivations
+into an addition at every such site — where a missed site does not fail, it
+silently answers ELF. `ObjectFormat` is that addition made once. This is the
+substance of [#597](https://github.com/mcpp-community/mcpp/issues/597)'s
+"changes the target model rather than extending a table", and with §3.1 having
+answered the standard-library half, #597 is now one problem rather than two.
+
+**Android's placement is the modelling decision.** `env = "android"` on a
+`linux` OS, not `os = "android"`: the kernel is Linux, so ELF, the `unix`
+family and `nasm -f elf64` are already right, and an OS value would have made
+every one of them wrong by default and required a new answer at each site. What
+differs from `gnu` is bionic, the loader path and the SDK, which is what an
+`env` value is for.
+
+What remains outside this pass, each blocked on something no engine work
+supplies:
+
+- **`xim:android-ndk`, `xim:emsdk`** (§7 step 5). Both recipes are measured
+  working in a scratch directory (§3.1); turning either into a payload means
+  fetching and republishing a multi-gigabyte vendor toolchain with a derived
+  133-file module surface. That is its own release, not a side effect of this
+  one — and the rows landing first is exactly §7's ordering argument, which
+  said doing the payloads first would make each row small. The rows turned out
+  to be the cheap half either way.
+- **The iPhoneOS SDK.** Not measurable on a Linux host, and §9.8 gives the
+  decision procedure rather than the measurement.
+- **`dist-android`, `dist-web`**. Each waits on its payload, not on its row.
 
 ### 9.8 The iOS SDK: a three-tier policy rather than an open question
 

README.md

@@ -419,6 +419,9 @@ list` reports for this machine):
 | `aarch64-none-elf` · `x86_64-none-elf` | llvm 22 — bare metal, no C library by default ² | preview |
 | `thumbv7em-none-eabi` · `thumbv8m.base-none-eabi` · `thumbv8m.main-none-eabihf` | llvm 22 — Cortex-M4/M7 soft float, M23, M33F/M55F ² | preview |
 | `riscv64-linux-musl` · `aarch64-linux-gnu` · `x86_64-macos` | — | planned |
+| `aarch64-linux-android` · `x86_64-linux-android` | needs `xim:android-ndk`; `import std` measured working on the NDK's clang | planned |
+| `aarch64-ios` | needs the iPhoneOS SDK, which is a licence question before it is a packaging one | planned |
+| `wasm32-emscripten` | needs `xim:emsdk`; `import std` measured working on `em++`, and the target model is [#597](https://github.com/mcpp-community/mcpp/issues/597) | planned |
 
 `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

README.zh-CN.md

@@ -406,6 +406,9 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 | `aarch64-none-elf` · `x86_64-none-elf` | llvm 22——裸机,默认不带 C 库 ² | preview |
 | `thumbv7em-none-eabi` · `thumbv8m.base-none-eabi` · `thumbv8m.main-none-eabihf` | llvm 22——Cortex-M4/M7 软浮点、M23、M33F/M55F ² | preview |
 | `riscv64-linux-musl` · `aarch64-linux-gnu` · `x86_64-macos` | — | planned |
+| `aarch64-linux-android` · `x86_64-linux-android` | 待 `xim:android-ndk`;`import std` 在 NDK 自带的 clang 上已实测可用 | planned |
+| `aarch64-ios` | 待 iPhoneOS SDK,而它先是一个许可问题再是一个打包问题 | planned |
+| `wasm32-emscripten` | 待 `xim:emsdk`;`import std` 在 `em++` 上已实测可用,目标模型见 [#597](https://github.com/mcpp-community/mcpp/issues/597) | planned |
 
 `verified` 该行的镜像已被构建**并运行**过,qemu 与 wine 都算 · `preview` 可构建
 可链接,未记录过模拟器运行 · `planned` 已登记在词表中,尚未接线 —— 面向这类目标

docs/21-the-target-triple.md

@@ -38,19 +38,26 @@ and the build reports what it resolved.
 
 | Segment | Content | Example |
 |---|---|---|
-| `arch` | instruction set | `x86_64`, `aarch64`, `riscv64` |
-| `os` | operating system, or `none` | `linux`, `windows`, `macos`, `none` |
-| `env` | see below — it is a different axis per platform | `gnu`, `musl`, `msvc`, `elf` |
+| `arch` | instruction set | `x86_64`, `aarch64`, `riscv64`, `wasm32` |
+| `os` | operating system, or `none` | `linux`, `windows`, `macos`, `ios`, `emscripten`, `none` |
+| `env` | see below — it is a different axis per platform | `gnu`, `musl`, `msvc`, `android`, `elf` |
 
 The third segment is the one that repays attention, because it does not name
 the same kind of thing everywhere:
 
 | Platform | `env` names | Values |
 |---|---|---|
-| `linux` | the **C library** | `gnu` (glibc), `musl` |
+| `linux` | the **C library** | `gnu` (glibc), `musl`, `android` (bionic) |
 | `windows` | the **object ABI** | `gnu` (Itanium C++ ABI), `msvc` (Microsoft's) |
 | `none` | the **object format** | `elf` |
-| `macos` | nothing; the platform carries no segment | — |
+| `macos`, `ios`, `emscripten` | nothing; the platform carries no segment | — |
+
+`android` is a **C library** and therefore sits where `musl` sits, on a `linux`
+OS. That placement is the whole of the modelling decision: the kernel *is*
+Linux, so ELF, the `unix` family and `nasm -f elf64` are already right, and an
+`os = "android"` would have made every one of them wrong by default and needed
+a new answer at each site. What differs from `gnu` is bionic, the loader path
+and the SDK — which is exactly what an `env` value is for.
 
 On Windows the segment is frequently misread, because the word `gnu` suggests a
 C library that is not there. Measured on an artefact built for
@@ -68,6 +75,30 @@ openkal. `gnu` is LLVM's label for the non-MSVC ABI, inherited from MinGW, and
 clang requires that spelling to select the right internal toolchain. mcpp
 cannot rename it.
 
+### The object format is an axis, not a derivation
+
+A triple's binary format used to be nothing at all: it was re-derived from `os`
+wherever it was needed. `is_pe()` asked `os == "windows"`, artifact naming asked
+again, the packer asked a third time. That is affordable while the answer has
+two values.
+
+`wasm32` is the first target in mcpp's vocabulary whose format is neither, and a
+third value turns those derivations into an addition **at every such site** — and
+a site that is missed does not fail. It silently answers ELF, because ELF is
+what every `else` branch in the tree assumes. So the format is now one answer:
+
+| target | format |
+|---|---|
+| `x86_64-linux-gnu`, `aarch64-linux-android`, `riscv64-none-elf` | ELF |
+| `aarch64-macos`, `aarch64-ios` | Mach-O |
+| `x86_64-windows-gnu`, `x86_64-windows-msvc` | PE |
+| `wasm32-emscripten` | wasm |
+
+It is **not** the same question as "is there an operating system to link
+against". A bare-metal RISC-V image is ELF with no OS; a wasm module has an
+OS-like layer (Emscripten's POSIX emulation) and is not ELF. Merging the two
+axes is the mistake this replaces.
+
 ## Declining The Third Segment
 
 `<arch>-<os>` is a complete target on every platform:
@@ -444,6 +475,10 @@ other's rows.
 | `thumbv8m.base-none-eabi` | preview | `llvm@22.1.8` | payload | payload | payload | payload |
 | `thumbv8m.main-none-eabi` | verified | `llvm@22.1.8` | payload | payload | payload | payload |
 | `thumbv8m.main-none-eabihf` | preview | `llvm@22.1.8` | payload | payload | payload | payload |
+| `aarch64-linux-android` | planned | — | planned | planned | planned | planned |
+| `x86_64-linux-android` | planned | — | planned | planned | planned | planned |
+| `aarch64-ios` | planned | — | planned | planned | planned | planned |
+| `wasm32-emscripten` | planned | — | planned | planned | planned | planned |
 
 `payload` a toolchain payload here produces it · `graph` no payload, but a
 dependency can supply the system · `system` located on the machine, not

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

@@ -32,18 +32,24 @@ C 库。选中 `x86_64-linux-musl` 就是选中 musl-gcc 载荷,选中
 
 | 段 | 内容 | 例 |
 |---|---|---|
-| `arch` | 指令集 | `x86_64`、`aarch64`、`riscv64` |
-| `os` | 操作系统,或 `none` | `linux`、`windows`、`macos`、`none` |
-| `env` | 见下 —— 它在每个平台上是不同的轴 | `gnu`、`musl`、`msvc`、`elf` |
+| `arch` | 指令集 | `x86_64`、`aarch64`、`riscv64`、`wasm32` |
+| `os` | 操作系统,或 `none` | `linux`、`windows`、`macos`、`ios`、`emscripten`、`none` |
+| `env` | 见下 —— 它在每个平台上是不同的轴 | `gnu`、`musl`、`msvc`、`android`、`elf` |
 
 第三段值得留意,因为它在各处命名的并不是同一类东西:
 
 | 平台 | `env` 命名 | 取值 |
 |---|---|---|
-| `linux` | **C 库** | `gnu`(glibc)、`musl` |
+| `linux` | **C 库** | `gnu`(glibc)、`musl`、`android`(bionic) |
 | `windows` | **对象 ABI** | `gnu`(Itanium C++ ABI)、`msvc`(微软的) |
 | `none` | **对象格式** | `elf` |
-| `macos` | 无;该平台不带这一段 | — |
+| `macos`、`ios`、`emscripten` | 无;该平台不带这一段 | — |
+
+`android` 是一个 **C 库**,所以它落在 `musl` 落的那个位置上,OS 段仍是 `linux`。
+这个位置就是这处建模决定的全部:内核**就是** Linux,所以 ELF、`unix` family、
+`nasm -f elf64` 全都已经是对的;而一个 `os = "android"` 会让这三样默认全错,并
+且要求在每一处站点给出一个新答案。它与 `gnu` 的差别是 bionic、加载器路径和 SDK
+—— 而这恰好就是 `env` 这一段存在的意义。
 
 在 Windows 上这一段经常被读错,因为 `gnu` 这个词暗示了一个并不在场的 C 库。
 对一份按构建期体系为 `x86_64-windows-gnu` 构建的产物实测:
@@ -59,6 +65,27 @@ compiler-rt,C 库是 musl,C++ 运行时是 libc++,平台是 openkal。`gnu` 是
 LLVM 词表里「非 MSVC 的那套 ABI」的标签,继承自 MinGW,而 clang 需要这个
 拼写来选中正确的内部工具链。mcpp 改不了它。
 
+### 对象格式是一个轴,不是一处推导
+
+一个三元组的二进制格式过去根本不是任何东西:它在每一处需要它的地方从 `os` 重新
+推导一遍。`is_pe()` 问 `os == "windows"`,产物命名再问一遍,打包器问第三遍。答案
+只有两个取值时,这是负担得起的。
+
+`wasm32` 是 mcpp 词表里第一个格式不属于那两个的目标,而第三个取值会把那些推导变成
+**在每一处这样的站点上的一次添加** —— 而漏掉的那一处不会报错。它会静默地答 ELF,
+因为 ELF 正是这棵树里每一个 `else` 分支所假设的东西。于是格式现在是一个答案:
+
+| 目标 | 格式 |
+|---|---|
+| `x86_64-linux-gnu`、`aarch64-linux-android`、`riscv64-none-elf` | ELF |
+| `aarch64-macos`、`aarch64-ios` | Mach-O |
+| `x86_64-windows-gnu`、`x86_64-windows-msvc` | PE |
+| `wasm32-emscripten` | wasm |
+
+它与「有没有一个操作系统可供链接」**不是**同一个问题。一个裸机 RISC-V 映像是 ELF
+且没有 OS;一个 wasm 模块有一层类 OS 的东西(Emscripten 的 POSIX 模拟)而不是
+ELF。把这两个轴并成一个,正是这处改动要消除的那个错误。
+
 ## 省略第三段
 
 `<arch>-<os>` 在每个平台上都是一个完整的目标:
@@ -398,6 +425,10 @@ CRT;图供给时是 `musl`。一个目标字符串,两个不同的 C 库 ——
 | `thumbv8m.base-none-eabi` | preview | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
 | `thumbv8m.main-none-eabi` | verified | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
 | `thumbv8m.main-none-eabihf` | preview | `llvm@22.1.8` | 载荷 | 载荷 | 载荷 | 载荷 |
+| `aarch64-linux-android` | planned | — | planned | planned | planned | planned |
+| `x86_64-linux-android` | planned | — | planned | planned | planned | planned |
+| `aarch64-ios` | planned | — | planned | planned | planned | planned |
+| `wasm32-emscripten` | planned | — | planned | planned | planned | planned |
 
 `载荷` 这里有工具链载荷产出它 · `图` 没有载荷,但依赖可以供给系统 ·
 `系统` 在机器上被找到,不是 mcpp 装的 · `SDK` 平台自己的 ·