Merge T3: runtime_search_dir, the stamp rule, the prepare role and role constants (#701, #702)

Conflicts resolved: the epoch-3 comment carries both reasons (#703, #702);
a link edge's one order-only list carries the deployed DLLs and the prepare
phonies; the runtime-search-dir residue mirror lands in T2's restructured root
block. The prepare post-condition asks for a populated directory rather than
an existing one, because ninja creates a stamp's parent before the command
runs; e2e 791 checks a stamp beside and inside the directory.

Author: speak-agent

docs/04-mcpp-toml.md

@@ -1484,10 +1484,13 @@ For one compatibility train, `library_dirs` maps only to runtime search,
 `capabilities` maps to required run-phase capability requirements. None of
 these legacy fields creates a provider.
 
-`library_dirs` has a build-program form for a directory only a build.mcpp can
-locate (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`): `mcpp::runtime_library_dir(dir)`
-(2026.9.27.1+, protocol 12; [30 — Build Programs](30-build-mcpp.md)), which
-joins this same field.
+`runtime_search_dirs` has a build-program form for a directory only a
+build.mcpp can locate (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`, a directory
+a `prepare` action populates): `mcpp::runtime_search_dir(dir)` (protocol 12;
+[30 — Build Programs](30-build-mcpp.md)), which joins this same field
+directly — not the legacy `library_dirs` above, which gains no directive of
+its own. The directory need not exist when the program runs; a `prepare`
+action may populate it later, at build time.
 
 `target/<triple>/<fp>/resolution.json` schema 2 stores the RuntimeBinding,
 canonical requirements/providers/artifacts, LinkIntent, platform search

docs/30-build-mcpp.md

@@ -186,16 +186,28 @@ a.submit();
 The strings must outlive the action. `a.id = ("toy:" + stem).c_str()` hands it a
 pointer into a temporary that is gone by `submit()`.
 
-### The four roles
+### The five roles
 
-`role` decides where the edge's outputs go and when the edge runs.
+`role` decides where the edge's outputs go and when the edge runs. Spell it
+with the `mcpp::roles` constants (`mcpp::roles::source`, `::check`,
+`::object`, `::artifact`, `::prepare`), not a bare string: an engine that does
+not know a constant refuses to compile the rule package, naming it, instead
+of reading a misspelt string as `source` (SPEC-007 R3.6).
 
 | `role` | outputs | ordering |
 |---|---|---|
 | `source` | compilable ones join the compile set | every compile edge of the declaring package waits for them |
 | `check` | a stamp file | runs alongside compilation; `blocking = true` makes compiles wait |
 | `object` | join the **link** set | the link edge consumes them |
 | `artifact` | a new file | its inputs are link outputs, so it runs after the link |
+| `prepare` | a stamp file, plus one declared directory (`output_dir`) the command populates | every compile edge *and* every link edge in the plan wait for it |
+
+`prepare` is for construction whose file names are not known when the rule
+runs — installing a package-manager prefix, unpacking an SDK — and is what
+SPEC-007 (`docs/specs/build-plugins.md`) asks a dependency-adapter rule to use
+instead of a blocking `check`; see docs/30's own section on the role for the
+full contract (the post-condition on `output_dir`, and the R1.3 warning a
+rerun input inside it earns).
 
 ### Declared inputs, and the compiler among them
 

docs/31-authoring-a-rule-package.md

@@ -1413,10 +1413,12 @@ Link intent 把各个发现阶段分开处理：
 映射到必需的运行期 soname 要求，`capabilities` 映射到必需的运行期
 能力要求。这些遗留字段都不创建提供者。
 
-`library_dirs` 有一个构建程序形态，用于一个只有 build.mcpp 才能定位的目录
-（一个 vcpkg 前缀的 `bin/`、一个 Qt SDK 的 `bin/`）：`mcpp::runtime_library_dir(dir)`
-（2026.9.27.1+，protocol 12；[30 —— 构建程序](30-build-mcpp.md)），并入的是
-同一个字段。
+`runtime_search_dirs` 有一个构建程序形态，用于一个只有 build.mcpp 才能定位的
+目录（一个 vcpkg 前缀的 `bin/`、一个 Qt SDK 的 `bin/`、一个 `prepare` action
+填充的目录）：`mcpp::runtime_search_dir(dir)`（protocol 12；
+[30 —— 构建程序](30-build-mcpp.md)），直接并入的就是这一个字段——不是上面
+那个不再获得新指令的遗留字段 `library_dirs`。这个目录在该程序运行时不必
+存在；一个 `prepare` action 可能在构建期之后才把它填充起来。
 
 `target/<triple>/<fp>/resolution.json` schema 2 存储 RuntimeBinding、
 规范化后的要求/提供者/产物、LinkIntent、平台发现机制与链接后判定。

docs/zh/04-mcpp-toml.md

@@ -174,16 +174,25 @@ a.submit();
 这些字符串必须比 action 活得久。`a.id = ("toy:" + stem).c_str()` 交给它
 的是一个指向临时对象的指针，而该临时对象在 `submit()` 之前就已经消失。
 
-### 四种 role
+### 五种 role
 
-`role` 决定这条边的输出去哪里，以及这条边什么时候跑。
+`role` 决定这条边的输出去哪里，以及这条边什么时候跑。用 `mcpp::roles`
+常量拼写它(`mcpp::roles::source`、`::check`、`::object`、`::artifact`、
+`::prepare`)，不要用裸字符串：一个不认识某个常量的引擎会拒绝编译这个规则包
+并指出它，而不是把一个拼错的字符串读成 `source`(SPEC-007 R3.6)。
 
 | `role` | 输出 | 次序 |
 |---|---|---|
 | `source` | 可编译的那些进入编译集合 | 声明它的包的每条编译边都等它 |
 | `check` | 一个 stamp 文件 | 与编译并行；`blocking = true` 让编译等它 |
 | `object` | 进入**链接**集合 | 链接边消费它们 |
 | `artifact` | 一个新文件 | 它的输入是链接产物，所以它在链接之后跑 |
+| `prepare` | 一个 stamp 文件，加上一个声明的目录(`output_dir`)由命令去填充 | 整个构建计划里的每条编译边**与**每条链接边都等它 |
+
+`prepare` 用于命令运行时文件名还不知道的施工——把一个包管理器的前缀装起来、
+解开一个 SDK——也是 SPEC-007(`docs/specs/build-plugins.md`)要求依赖适配类
+规则包使用的形态，而不是一个 blocking 的 `check`；完整的约定(`output_dir`
+上的后置条件、命中它内部的重跑依据会得到的 R1.3 警告)见 docs/30 自己那一节。
 
 ### 声明的输入，以及其中的编译器