feat: the engine gaps left open after the SDK batch (2026.9.12.2)

Implements .agents/docs/2026-09-12-engine-gaps-after-the-sdk-batch.md (M1-M9).

- #618: `[targets.<name>] windows_subsystem` and `windows_entry`, rendered per
  ABI onto the declaring executable's own link (`/SUBSYSTEM:` with the CRT
  `/ENTRY:` symbol on MSVC, `-mwindows`/`-municode` on GNU), inert off PE, and
  refused on library targets. Build-program protocol 10 adds the
  `windows-subsystem` and `windows-entry` directives for a named target.
- T1: the fast path compares the toolchain request (`--toolchain`,
  `MCPP_TOOLCHAIN`, and `[toolchain] default`); a build asking for another
  toolchain no longer replays the previous one.
- #615: `runtime.deploy = [{ from, to }]` places runtime files in a directory
  relative to the executable, in mcpp.toml and in descriptors, and `mcpp pack`
  carries both `deploy_files` and `deploy` at the same relative paths.
- `[target.<selector>.abi] threads` as a typed graph-wide switch, with
  `requires_abi` on a package or feature refused before compilation when the
  root does not state it.
- #613: a dependency's install hook receives MCPP_COMPILER, MCPP_CXX_STDLIB and
  the target names, computed by the function the build-program environment
  uses; docs state the `mcpp:c++-abi` recipe for source-built static packages.
- #614: one function decides an xlings invocation's environment, the Windows
  project scope is restored after each invocation, and xlings' own error lines
  follow a failed install.
- #609 and G1: a documented toolchain hazard, and the refusal that names
  `[target.<selector>.xlings.workspace]`, with examples/13 using it.

Author: speak-agent

.agents/docs/2026-09-12-a-verified-web-run-that-asked-the-host-for-node.md

@@ -5,7 +5,7 @@ status: landed
 
 # A verified Web run that asked the host for node
 
-**Status:** implemented in mcpp 2026.9.12.1 and openxlings/xim-pkgindex#823.
+**Status:** implemented in mcpp 2026.9.12.2 (2026.9.12.1 was not published) and openxlings/xim-pkgindex#823.
 
 ## What was measured
 

.agents/docs/2026-09-12-engine-gaps-after-the-sdk-batch.md

@@ -1,16 +1,15 @@
 ---
 subject: triage
-status: active
+status: landed
 ---
 
 # The engine gaps left open after the SDK batch
 
-**Status:** reviewed 2026-09-12. The four questions in the first draft were
-answered, and the answers are recorded in §9. Three statements in the first
-draft were then measured and corrected: two recorded gaps already have an
-existing mechanism (§2, §5.2), and a new defect was found (§7). The
-implementation is one mcpp PR carrying the next date version. 2026.9.12.1 (#617)
-is merged and unreleased, so its change ships with that PR.
+**Status:** landed in mcpp 2026.9.12.2. The four questions in the first draft
+were answered in review (§9), and three statements were measured and corrected
+before implementation (§2, §5.2, §7). The corrections made during
+implementation are recorded in §11. The ecosystem changes E1 and E2 follow the
+release (§10).
 
 ## 0. Scope, and the ledger it starts from
 
@@ -108,15 +107,15 @@ console program may define `wmain`.
 
 | target | `windows_subsystem = "windows"` renders | decided by |
 |---|---|---|
-| PE, MSVC style: cl, clang-cl, clang targeting `*-windows-msvc` | `/SUBSYSTEM:WINDOWS` plus the entry's `/ENTRY:` symbol, spelled with `-Wl,` under a GNU-style driver | `plan.rcStyle == "msvc"` |
-| PE, GNU style: MinGW gcc, clang targeting `*-windows-gnu` | `-mwindows`, plus `-municode` for a wide entry | `plan.rcStyle == "gnu"` |
+| PE, MSVC style: cl, clang-cl, clang targeting `*-windows-msvc` | `/SUBSYSTEM:WINDOWS` plus the entry's `/ENTRY:` symbol, spelled with `-Wl,` under a GNU-style driver | `pe_msvc_abi` (§11.1) |
+| PE, GNU style: MinGW gcc, clang targeting `*-windows-gnu` | `-mwindows`, plus `-municode` for a wide entry | `pe_msvc_abi` (§11.1) |
 | ELF, Mach-O, Wasm | nothing; no diagnostic; byte-identical artefact | `ObjectFormat` |
 
 `"console"` with `"main"` renders nothing on every target, because both are the
-linker's defaults. A non-default entry with the console subsystem renders only
-the entry. The dialect is read from `rcStyle`, the field the plan already uses to
-choose between rc/llvm-rc and windres (`plan.cppm:262`), so resources and the
-subsystem cannot disagree about the linker they address.
+linker's defaults. On the MSVC ABI any other combination renders both flags
+(§11.2). The ABI is answered by `pe_msvc_abi`, the predicate the import library
+flag already uses, and the emitter spells the flag for the linker it invokes
+(§11.1).
 
 ### 1.4 Scope
 
@@ -443,7 +442,7 @@ Each angle states what the design does, and what would be wrong with the
 alternative.
 
 - **Architecture.** Every change lands on a mechanism that already exists:
-  `LinkUnit::linkFlags` and `rcStyle` (§1), the layer requirement check (§2), the
+  `LinkUnit` and the PE link-flag predicate (§1), the layer requirement check (§2), the
   `runtime` table's skipping of unknown sub-keys (§4), the xlings workspace
   selector (§5.1), the graph-global dialect channel and the dependency cache key
   (§5.2), and the fast path's recorded inputs (§7). No new channel carries raw
@@ -462,7 +461,7 @@ alternative.
   placed where older parsers skip rather than hang: `runtime.deploy` (§4.2),
   `requires_abi` as an unknown feature key (§5.2). `console`/`main` render
   nothing, so no existing Windows command line changes.
-- **Cross-platform.** Rendering is decided by `ObjectFormat` and `rcStyle`; a key
+- **Cross-platform.** Rendering is decided by the object format and the PE link-flag predicate; a key
   that means nothing for a format is inert and byte-identical there. The Windows
   criteria run on Windows CI, not on Wine.
 - **Consistency.** One vocabulary per concept: `mcpp:c++-abi` is the standard
@@ -520,3 +519,66 @@ M1 to M4, M6, M7 and M8 are independent and are implemented in parallel. The
 three ecosystem changes follow the release, because each adopts a key only the
 new engine reads, and E2's descriptor must be checked against the index's
 minimum engine version before it is published.
+
+## 11. Corrections made during implementation
+
+Each item states what the sections above said, what was measured or read in the
+code, and what was built instead.
+
+1. **§1.3, the discriminator.** The ABI is not read from `plan.rcStyle`.
+   `LinkUnit` carries the declared words, and the emitter renders them, because
+   only the emitter knows whether the link is a separate linker invocation, which
+   decides between `/SUBSYSTEM:` and `-Wl,/SUBSYSTEM:`. The ABI is answered by
+   `pe_msvc_abi`, extracted from `pe_link_flag`, so the import library and the
+   subsystem cannot address two different linkers.
+2. **§1.3, the MSVC row.** Both `/SUBSYSTEM:` and `/ENTRY:<entry>CRTStartup` are
+   written whenever either key differs from its default. Without `/SUBSYSTEM:`,
+   link.exe infers the subsystem from the entry function the objects define, so
+   `WinMain` with the console subsystem would link as a GUI program; without
+   `/ENTRY:`, the GUI subsystem selects `WinMainCRTStartup`, which a portable
+   `int main()` does not satisfy.
+3. **§2.3 item 1, the order.** The layer requirement check runs in target-side
+   resolution, after the dependency graph is installed, and it is not moved ahead
+   of provisioning. A package's manifest may live inside its payload, so the
+   complete set of requirements is known only after installation. The hook
+   environment is what lets an install hook refuse before it compiles.
+4. **§2.3 item 2, the values.** `MCPP_TARGET` in a hook follows the build-program
+   rule: the requested triple, or the host triple for a native build. The six
+   values are computed by `install_hook_env`, from which the build-program
+   environment also takes them, in their existing order, so no build program's
+   re-run key changes.
+5. **§3.1, absent and empty on Windows.** The CRT defines `_putenv_s(key, "")` as
+   removal, so the Windows branch already produced an absent
+   `XLINGS_PROJECT_DIR`, and the two platforms did not disagree about global
+   mode. What was wrong on Windows was the lifetime: the value stayed in mcpp's
+   environment after the invocation. The asymmetry that did exist was on POSIX,
+   where the `install_packages` fallback spelled global mode by hand whatever the
+   project directory was.
+6. **§3.2, the scope of the guard.** Only `XLINGS_PROJECT_DIR` is scoped.
+   `XLINGS_HOME` and the PATH prefix are left process-wide on Windows, as before;
+   scoping them has not been measured on Windows and is not part of this change.
+   The hook variables of §2.3 are applied by the dependency installer's own
+   scope rather than by the xlings environment function.
+7. **§4.3, the TOML form.** mcpp's TOML layer refuses an array of tables in any
+   section not on an allowlist, and `runtime.deploy` had to join it. The unit
+   test written for the key reported this before an end-to-end test or a user
+   could.
+8. **§5.2, rendering.** Rendering is decided by the object format rather than by
+   the driver: `-pthread` on every target that is neither PE nor freestanding,
+   nothing on PE and nothing on a freestanding target. The switch reaches the
+   root's `dialect_cxxflags`, `cflags` and `ldflags` and every dependency's
+   `cflags`. The MinGW driver would accept `-pthread`; it is not rendered there,
+   and threads on that ABI are outside this change's criteria.
+9. **§7, the named set.** A recorded build is replayed only for the same target
+   triple, profile, cache mode, requested features and toolchain request. The
+   toolchain request is the command-line override (`--toolchain`,
+   `MCPP_TOOLCHAIN`) together with the machine default (`[toolchain] default`).
+   `--offline`, `--locked` and `--jobs` change how a resolution is fetched,
+   checked or executed, not what it chooses, and are not compared. An entry
+   written before the `toolchain=` line declines once.
+10. **§7, the criterion.** A CI runner has one toolchain family installed, so the
+    A-B-A test requests the platform's own toolchain through `--toolchain` and
+    asserts that resolution runs, which the fast path skips. The machine-default
+    leg switches to a second installed version of the same family and asserts
+    the version string in the artefact; it reports itself as not measured where
+    no second version is installed.

.agents/docs/README.md

@@ -52,14 +52,14 @@ Records that declare one. Everything else is listed by date below.
 
 ### triage
 
-- [The engine gaps left open after the SDK batch](2026-09-12-engine-gaps-after-the-sdk-batch.md) — active
+- [The engine gaps left open after the SDK batch](2026-09-12-engine-gaps-after-the-sdk-batch.md) — landed
 - [Six open issues: what each one actually is, and what would answer it](2026-09-11-six-open-issues-analysis.md) — active
 
 ## By date
 
 ### 2026-09
 
-- [The engine gaps left open after the SDK batch](2026-09-12-engine-gaps-after-the-sdk-batch.md) — active
+- [The engine gaps left open after the SDK batch](2026-09-12-engine-gaps-after-the-sdk-batch.md) — landed
 - [A verified Web run that asked the host for node](2026-09-12-a-verified-web-run-that-asked-the-host-for-node.md) — landed
 - [Six open issues: what each one actually is, and what would answer it](2026-09-11-six-open-issues-analysis.md) — active
 - [SDK toolchains, the payload/engine seam, and openkal across iOS, Android and Web](2026-09-11-sdk-toolchains-and-ios-local-verification.md) — landed

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

@@ -203,11 +203,11 @@ jobs:
           [target.aarch64-ios-sim]
           runner = ["simctl-run"]
 
-          # Declared at the top level here and not in examples/13, because a
-          # tool declaration is not conditional on a target and this package
-          # exists for macOS alone. This fixture is macOS-only, so it can say
-          # it; a portable manifest cannot.
-          [xlings.workspace]
+          # Declared on the row that runs it, as examples/13 does. A target
+          # section's `xlings.workspace` is installed only when that target is
+          # built, so the step below that runs the simulator artefact through
+          # `simctl-run` is also the measurement that this declaration works.
+          [target.aarch64-ios-sim.xlings.workspace]
           "xim:apple-simulator-tools" = ""
           TOML
           cat > /tmp/iostest/src/main.cpp << 'CPP'

CHANGELOG.md

@@ -5,7 +5,9 @@
 
 ## [Unreleased]
 
-## [2026.9.12.1] - 2026-09-12
+## [2026.9.12.2] - 2026-09-12
+
+2026.9.12.1 未单独发布,其条目并入本版本。
 
 ### Web 产物的运行不再依赖宿主的 `node`
 
@@ -34,6 +36,76 @@ Emscripten 链接产出的是首行为 `#!/usr/bin/env node` 的 JavaScript 启
   忽略它,所以配方可以先发;在此之前安装的 emsdk 载荷没有描述文件,行为与之前相同,重新
   安装后获得。
 
+### Windows GUI 可执行文件:`windows_subsystem` 与 `windows_entry`(#618)
+
+- `[targets.<name>]` 增加 `windows_subsystem = "console" | "windows"` 与
+  `windows_entry = "main" | "wmain" | "WinMain" | "wWinMain"`。它们是字段而不是链接标志,因为正确的
+  标志取决于 ABI:MSVC ABI 渲染为 `/SUBSYSTEM:` 与 CRT 启动符号 `/ENTRY:<entry>CRTStartup`(经 GNU
+  风格驱动时带 `-Wl,`),只要任一键偏离默认值两条都写出;GNU ABI 渲染为 `-mwindows` 与 `-municode`。
+  在 ELF、Mach-O 与 WebAssembly 上不产生任何标志,产物逐字节不变。
+- 只到达声明它们的可执行目标的链接;同包的其他可执行文件、测试二进制与消费者保持控制台子系统。库目标
+  声明任一键被拒绝,拒绝信息指出目标与键名;取值不在集合内被拒绝并列出可接受的取值。
+- 构建程序协议升至 10:`mcpp::windows_subsystem(target, value)` 与 `mcpp::windows_entry(target, value)`
+  为本包的可执行目标设置同一字段。指向未声明的目标、非可执行目标,或与 mcpp.toml 矛盾的取值,在应用任何
+  指令之前被拒绝;缓存命中的路径施加同一检查。
+- `[targets.<name>]` 不支持键的警告所列出的键表改为由解析器接受的键表生成;此前手写的副本漏掉了 `exports`。
+
+### 快路径比较工具链请求
+
+- 快路径此前比较目标三元组、profile、缓存模式与 feature,但不比较 `--toolchain`(即 `MCPP_TOOLCHAIN`)
+  与本机默认工具链(config.toml 的 `[toolchain] default`)。实测:以 gcc 构建后执行
+  `mcpp build --toolchain llvm@22.1.8`,输出 `Finished dev in 0.00s` 并保留 gcc 产物,解析阶段的检查
+  全部被跳过。
+- 构建缓存记录增加 `toolchain=` 行,`mcpp build` 与 `mcpp run` 的快路径都比较它。早于该行的记录被拒绝
+  一次,随后的构建重新写入。`--offline`、`--locked` 与 `--jobs` 不改变解析的选择,不参与比较。
+
+### `runtime.deploy`:把运行期文件放进相对可执行文件的目录(#615)
+
+- `[runtime] deploy = [{ from = "...", to = "..." }]` 与描述文件的 `runtime.deploy`:`from` 相对声明它的
+  包,`to` 相对可执行文件所在目录,`"."` 表示该目录本身。`deploy_files` 把每一项放在可执行文件旁,无法
+  满足从固定子目录读取的加载器,例如 macOS 上的 Vulkan loader 读取 `<可执行文件目录>/vulkan/icd.d`。
+- mcpp.toml 与描述文件使用同一条路径规则:以 `/` 分隔,不得为绝对路径、不得指定盘符、不得含空分量、`.`
+  或 `..` 分量;违反的项按序号被拒绝。同一目标位置的两个来源被拒绝,同名文件放进不同目录不构成冲突。
+  测试二进制看到同样的布局。
+- `mcpp pack` 把 `deploy_files` 与 `deploy` 的文件放到打包后可执行文件旁的同一相对位置;此前打包过程不读取
+  这两个列表中的任何一个。
+- 它是独立的键,而不是 `deploy_files` 的表形式:早于它的描述文件读取器在 `deploy_files` 中遇到 `{` 时
+  不会终止,而对不认识的 `runtime` 键会跳过。
+
+### 产物的 ABI 开关:`[target.<selector>.abi] threads` 与 `requires_abi`
+
+- 线程支持是整个产物共享的性质:标准库模块预构建、依赖扫描、每个包的每个翻译单元与链接必须一致。根
+  manifest 以 `[target.<selector>.abi] threads = true` 声明;在既非 PE 也非 freestanding 的目标上渲染为
+  `-pthread`,并经方言 flag 进入依赖缓存键。未知成员与非布尔的 `threads` 被拒绝。
+- 依赖以 `[package] requires_abi = { threads = true }` 或
+  `[features] <name> = { requires_abi = { threads = true } }` 声明需求;根包未满足时在编译之前被拒绝,
+  拒绝信息指出包与 feature,并给出满足它的表。依赖自己写的 `[target.<selector>.abi]` 被报告
+  (`abi/dependency-table`)且不生效。
+
+### 安装钩子收到已解析的工具链(#613)
+
+- 依赖包的安装钩子收到 `MCPP_COMPILER`、`MCPP_CXX_STDLIB`、`MCPP_TARGET`、`MCPP_TARGET_OS`、
+  `MCPP_TARGET_ARCH` 与 `MCPP_TARGET_ENV`,名称与取值同构建程序一致,由同一个函数计算。钩子可以据此拒绝
+  或诊断,但不得把某种变体构建进名称未体现该变体的存储目录。
+- 从源码构建静态库的包以 `requires = ["mcpp:c++-abi=<stdlib>"]` 声明它所针对的标准库;工具链解析出另一
+  实现的工程被拒绝,拒绝信息指出两个实现。docs/06、docs/22 与 docs/32 记录这一做法。
+
+### xlings 调用的环境与错误输出(#614)
+
+- 一次 xlings 调用的环境由一个函数决定,全局模式是不存在的 `XLINGS_PROJECT_DIR`。POSIX 把它渲染进
+  命令前缀;Windows 在调用期间以作用域守卫施加,调用结束后恢复原值,项目目录不再留在 mcpp 之后启动的
+  进程的环境中。`install_packages` 的回退路径此前在 POSIX 上无视项目目录、一律按全局模式拼写,现与直接
+  路径一致。
+- 安装失败时,xlings 自己的错误级别输出(含 `error`、`E_` 或以 `[xim]` 开头的行,最多最后 20 行)以
+  `xlings:` 前缀附在 mcpp 的诊断之后;此前 stderr 被丢弃。
+
+### 其他
+
+- `[target.<selector>.xlings]` 下写包名时,拒绝信息指出正确的位置 `[target.<selector>.xlings.workspace]`;
+  示例 13 与 iOS 模拟器 CI 夹具改用该写法声明 `xim:apple-simulator-tools`,示例 README 不再要求手动安装。
+- docs/20 记录 clang 与 MSVC STL 14.51 组合下 `std::find` 作用于宽平凡可比较类型时的已知工具链缺陷
+  (microsoft/STL#6294,#609)。
+
 ## [2026.9.11.4] - 2026-09-11
 
 ### iOS 三行:生态编译器与定位到的 SDK