2026.9.28.3: the build-plugin architecture -- mcpp.core, build information, members built once, batched placement, pack -p, the library interface (#734)

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-315 records.
+316 records.
 
 ## By subject
 
@@ -31,6 +31,7 @@ Records that declare one. Everything else is listed by date below.
 ### design
 
 - [An ecosystem design for mcpp and xlings: one authority per fact, and the work that follows from it](2026-09-28-ecosystem-design-and-optimisation-plan.md) — landed
+- [Build cost, foreign toolsets, the build-plugin architecture and the library surface: engine, plugin and index design (#734)](2026-09-28-build-cost-foreign-toolsets-and-library-surface-design.md) — active
 - [The compile database, `emit build-database`, and #701/#702: triage against the specifications, and one design](2026-09-26-compile-database-and-issue-699-design.md) — landed
 - [Issues #693 to #696: triage against mcpp's contracts, and one repair plan](2026-09-25-issues-693-696-triage-and-repair-plan.md) — landed
 - [Workspace inheritance, flag scoping and the published form: a unified repair plan (#690)](2026-09-25-issue-690-workspace-build-inheritance-consistency.md) — landed
@@ -108,6 +109,7 @@ Records that declare one. Everything else is listed by date below.
 
 - [Two days of mcpp and xlings: a review of what merged, what is known, and what is open](2026-09-28-ecosystem-review-of-two-days-of-mcpp-and-xlings.md) — active
 - [An ecosystem design for mcpp and xlings: one authority per fact, and the work that follows from it](2026-09-28-ecosystem-design-and-optimisation-plan.md) — landed
+- [Build cost, foreign toolsets, the build-plugin architecture and the library surface: engine, plugin and index design (#734)](2026-09-28-build-cost-foreign-toolsets-and-library-surface-design.md) — active
 - [Eight reports after 2026.9.27.1: implementation plan](2026-09-27-eight-reports-implementation-plan.md) — active
 - [Eight reports after 2026.9.27.1: what each one is, where it belongs, and one optimisation plan](2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md) — active
 - [The compile database, `emit build-database`, and #701/#702: triage against the specifications, and one design](2026-09-26-compile-database-and-issue-699-design.md) — landed

.github/workflows/ci-linux.yml

@@ -110,6 +110,9 @@ jobs:
       - name: The release canary runner runs each command under the named bash
         run: python3 tests/scripts/test_release_canaries.py
 
+      - name: The protocol table of SPEC-007 names the engine's protocol
+        run: python3 tests/scripts/test_protocol_table.py
+
       # Text-only, like the two steps around it, and it belongs here rather
       # than in the target-matrix workflow: that workflow runs the matrix, and
       # this asserts a property of the TABLE, which is readable without a

.github/workflows/measure-windows-tool-crt.yml

@@ -113,8 +113,10 @@ jobs:
           "$XLINGS_BIN" install qt-base@6.11.1 -y
           QT="$(cygpath -u "$USERPROFILE")/.xlings/data/xpkgs/xim-x-qt-base/6.11.1"
           test -x "$QT/bin/moc.exe" || { echo "::error::no moc.exe in $QT/bin"; exit 1; }
-          # What revision 1 of the recipe removes (task I2).
-          ( cd "$QT/bin" && ls vcruntime140*.dll msvcp140*.dll concrt140.dll vccorlib140.dll 2>/dev/null; \
+          # What revision 1 of the recipe removes (task I2). The published
+          # revision 1 no longer carries them, and `ls` of absent files exits 2,
+          # which `bash -e` would read as a failed install.
+          ( cd "$QT/bin" && { ls vcruntime140*.dll msvcp140*.dll concrt140.dll vccorlib140.dll 2>/dev/null || true; }; \
             rm -f vcruntime140*.dll msvcp140*.dll concrt140.dll vccorlib140.dll )
           echo "QT=$QT" >> "$GITHUB_ENV"
 

CHANGELOG.md

@@ -3,6 +3,73 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.9.28.3] - 2026-09-28
+
+本版本实施 #734 设计中 mcpp 的部分:构建插件体系的三层(`mcpp.core`、官方通用库、插件)、
+构建信息、工作区成员只构建一次、批量放置、`pack -p`、库接口规范的第一阶段与包的版本下限。
+设计、测量、任务划分与实施记录见
+`.agents/docs/2026-09-28-build-cost-foreign-toolsets-and-library-surface-design.md`,规范见
+SPEC-007 §9 与新的 SPEC-008。配套的 mcpp-plugins 0.17.0 以本版本为下限。
+
+### 行为变化
+
+- **被其他成员以 path 依赖使用的工作区成员只构建一次(E1)。** 消费方构建之前,成员在自己的目录中
+  作为自身构建的根构建一次,由它的 ninja 判断过期(包括成员根目录之外的头文件);消费方经 stage
+  边取得其对象与 BMI,按内容比较。条件是成员在消费方图中的构建键输入与它作为根时相等
+  (`package.index` 除外,它只记来源);不相等时照旧在消费方图中编译,`-v` 写出不同的输入。同时
+  构建的两个消费方以文件锁轮流使用成员目录。一个五成员 Windows 工作区的核心库此前被编译三次。
+- **程序旁的文件由一个进程放置(E4)。** 程序的 deploy 条目在两条及以上时成为一条 `stage_list`
+  边,读取规划写出的 `placements.list`;`mcpp stage --list` 对每个目的地保持单文件语义。在
+  Windows 首次构建上,1270 条单文件放置耗时 4.5 s,一个进程复制同样的文件耗时 0.5 s。
+- **库接口的第一阶段(E6,SPEC-008)。** `mcpp pack` 写出未进入发布闭包的导出模块(W2),"Withheld"
+  一行列出每个未发布的单元(此前没有接口根时显示 "(nothing)",而两个导出模块既未发布也未列出);
+  `mcpp build` 在包导入依赖(本工作区成员除外)的非公开模块时警告(W3);缺少接口根的警告写明对 `mcpp pack` 的后果
+  (W1)。全部为警告。
+- **快路径在一次确认之后恢复。** 编辑源码后的那次构建经完整路径确认了图,却不重写内容未变的
+  build.ninja,而快路径以 build.ninja 的时间比较每个源码;此前编辑之后的每次构建都被拒绝,直到图的
+  文本改变。现在确认时移动 build.ninja 的时间(e2e 832,2026.9.28.2 在 Linux 上同样复现)。
+- **快路径看见 path 依赖的整棵源码树。** 此前只扫描依赖的 `src/`;依赖在别处的 host module
+  (例如 mcpp-plugins 的 `deps/vcpkg.cppm`)编入消费方的构建程序,不在任何 ninja 边上,被编辑后
+  构建报告"无事可做"。现在扫描依赖的整棵树,跳过隐藏目录、`target` 与嵌套的包(e2e 831)。
+- **每个下载只占一行。** 非终端输出此前在开始时写一行 `Downloading <item> (<size>)`,完成时再写一行
+  `... done, <size> in <time>`;现在只写完成的一行,失败时写 `did not complete` 的一行。终端上进度条
+  原地刷新,结束时换成同样带大小与耗时的完成行。
+- **MSVC ABI 上的 clang 找不到工具集时说明原因。** 默认的 `msvc@system` 在没有带 C++ 工具的
+  Visual Studio 实例时,此前静默继续,随后在预编译 `mcpp` 模块时以 `'cstdio' file not found` 失败;
+  现在解析时给出警告,写出安装与指定托管工具集的命令(在屏蔽 Visual Studio 的 runner 上测得)。
+- **`mcpp.core` 的输出不再把 `FILE` 带入模块接口。** `mcpp::report` 只经 `printf` 输出;此前 GCC
+  拒绝在 `import mcpp;` 之后 `#include <cstdio>` 的构建程序(e2e 651)。
+
+### 特性
+
+- **`mcpp.core`(E8,协议 14)。** 引擎接口以 `mcpp.core` 为名,`mcpp` 是永久等价的写法。
+- **构建信息(E2,协议 14)。** `mcpp::tool(role)`、`abi_tool(role)`、`tool_env()`、
+  `toolset_identity()`、`msvc_instance_dir()`、`ninja_program()`、`cxx_runtime()`、
+  `msvc_crt_linkage()` 以事实陈述解析出的工具链与程序的 C++ 运行时契约,取自引擎自身命令行所读的
+  同一来源。
+- **结构化诊断(E11,协议 14)。** `mcpp::report({severity, message, impact, hint})` 以引擎的形式
+  呈现,进入 JSON 输出,缓存命中时重放。
+- **缺失的构建程序模块指出 feature(E7)。** 模块只在依赖未启用的 feature 之后提供时,错误写出包名、
+  feature 名与应加的一行。
+- **插件模块的名字(E10)。** `mcpp.<自己的命名空间>.*` 不再被警告;保留的第二段(`core`、
+  `plugins`、`deps`、`rules`、`dist`、`tools`)只属于命名空间 `mcpp` 的包。
+- **`mcpp pack -p <member>`(E3)。** 在工作区根目录打包某个成员,结果与在成员目录中打包相同。
+- **包的版本下限(E9)。** `[package] mcpp = ">=<release>"` 与 `[workspace.package] mcpp`;
+  低于下限的引擎在其他工作之前停止,写出升级命令;只接受 `>=`。
+- **`[lib]` 报告未知键(E12)。** 此前拼错的 `path` 被静默接受。
+- **快路径在 macOS、Windows 与自带 sysroot 的目标上生效(E5)。** 运行期校验只含 ELF/glibc 规则,在这些目标上
+  提前返回而不写校验记录,快路径因此找不到已校验的产物快照,每次构建都走完整路径(macOS 上 e2e 645、831、
+  832 读出 `no validated artifact snapshot is recorded`)。现在这些目标记录产物的戳记,判定为通过(没有适用的
+  规则);产物被重新链接时快路径仍交回完整路径。`-v` 下每个拒绝点以一句话写出其条件。
+
+### 兼容性
+
+- 协议升至 14:使用 §9 新接口的构建程序在旧引擎上编译失败并指出缺少的名字;以
+  `[package] mcpp` 声明下限的包在旧引擎上得到一条"不支持的键"警告。
+- 升级后的第一次构建各付一次代价:每个构建程序因上下文新增变量而重新运行一次;被共享的工作区
+  成员在消费方中改为暂存,其对象在成员目录中编译一次;程序旁的放置边形状改变而运行一次(内容相同
+  的文件不重写)。
+
 ## [2026.9.28.2] - 2026-09-28
 
 本版本实施 2026-09-28 生态设计中 mcpp 的部分(WS1、WS2、WS3、WS7、WS8、WS10 与决定 D7),关闭

docs/04-mcpp-toml.md

@@ -103,6 +103,22 @@ mcpp does not read is reported, as in `[build]`: a warning, and an error under
 resources = "res"
 ```
 
+`mcpp = ">=<release>"` (mcpp 2026.9.28.3+) states the oldest mcpp release the
+package supports. It is a floor, not a pin: the release a project installs is
+the one `.xlings.json` names. Only the `>=` form is accepted, because a bare
+release means "exactly" elsewhere in mcpp; a bare release and a value that is
+not a release are refused with the spelling that is meant. An engine below the
+floor stops before any other work, naming the package, the floor, its own
+release and the command that installs a newer one. `[workspace.package] mcpp`
+states it once for every member. An engine older than 2026.9.28.3 ignores the
+key with a warning.
+
+```toml
+[package]
+name = "myplugin"
+mcpp = ">=2026.9.28.3"
+```
+
 #### Dialect flags and the `import std` BMI
 
 Some flags change what the standard library's headers declare, so the precompiled `import std`
@@ -1022,6 +1038,10 @@ path = "src/capi/lua.cppm"    # Override the default lib-root location
 ```
 
 Default convention: `src/<last segment of package name>.cppm` (e.g. package name `mcpplibs.cmdline` → `src/cmdline.cppm`).
+`path` is the only key of the table; any other key is reported, as in `[build]`
+(mcpp 2026.9.28.3+). The lib root is the interface root of SPEC-008: the module a
+packed library publishes, with what it re-exports, and the module a build
+program imports from a host-module dependency.
 ### 2.5 `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`
 
 Moved to [05 — Dependencies and Resolution](05-dependencies.md).

docs/07-workspace.md

@@ -413,6 +413,28 @@ fan-out continues; a timed-out build fails that member; `--workspace-timeout` st
 the fan-out and lists what did not run instead of leaving the CI job to kill the
 process (which discards everything it had to say).
 
+### 5.4 A member used by other members is built once (mcpp 2026.9.28.3+)
+
+A member that other members use as a path dependency is built once, in its own
+directory, and every member that uses it takes its objects and module
+interfaces from there. A `--workspace` build and separate `-p` builds of two
+programs therefore compile a shared library member once, where each program
+used to compile it again in its own directory.
+
+- **Staleness is the member's own.** Before a consumer builds, the member's
+  own build runs, and its ninja decides what is stale, including an input
+  outside the member's root (a header under `../3rdParty`).
+- **Equal build keys are the condition.** The member's build key in the
+  consumer's graph must equal its key as the root of its own build; the key
+  covers the toolchain, the flags, the profile and the features. A member that
+  a consumer builds differently (another feature set, for example) is compiled
+  in that consumer's graph, as before; `-v` states the input that differs.
+- **One build at a time.** Two consumers built at once take turns on the
+  member's directory.
+- **Scope.** The rule applies in the default cache mode (`--cache off` compiles
+  everything in the graph that asks for it) and to members only; a path
+  dependency outside the workspace has one consumer and keeps its behaviour.
+
 ## 6. Directory Layout
 
 The recommended directory layout for a workspace:

docs/10-pack-and-release.md

@@ -147,6 +147,7 @@ mcpp pack --profile dev                # build with a different profile (default
 mcpp pack --dev                        # the same, as `build` and `run` spell it; --profile wins over it
 mcpp pack --message-format json        # one mcpp.pack envelope on stdout (mcpp 2026.9.16.1+)
 mcpp pack --no-strip                   # ship the artifacts as built
+mcpp pack -p app --format release      # a workspace member, as if run in its directory
 mcpp pack --debug-symbols dbg/         # write the separated *.debug files under dbg/
 mcpp pack --format msi --features installer   # activate root-package features for the pack
 ```
@@ -158,6 +159,11 @@ one distribution is declared under `[feature-deps.<f>]` with `tools = [...]` and
 only by the pack that names `<f>`. `mcpp run --format <name> --features <LIST>` hands
 the same features to the pack it performs.
 
+`-p <member>` (mcpp 2026.9.28.3+) packs a workspace member from the workspace
+root: the member is resolved as every other `-p` resolves it, and the pack runs in
+its directory, so the result is the one `mcpp pack` in that directory produces. A
+relative `-o` keeps meaning the directory the command was typed in.
+
 `--release` and `--dev` (mcpp 2026.9.16.1+) are the shorthands `build` and `run`
 take, with the same precedence: `--profile` wins over either, on all three
 commands.

docs/12-binary-distribution.md

@@ -137,6 +137,23 @@ error: the published interface imports mathkit:secret , which no unit in this
 Restructure so the interface does not reach it, or make it an `export module`
 partition and accept that its source is published.
 
+### Public modules, and what `mcpp pack` and `mcpp build` report (mcpp 2026.9.28.3+)
+
+A package's public modules are the lib root's module and what it re-exports
+with `export import`, transitively (SPEC-008). They are what a consumer may
+import; the published closure also carries what they import without
+re-exporting, because a consumer needs it to build their interfaces. The
+"Withheld" row lists every unit that is not published, including when the
+package has no lib root. The three conditions below are warnings: a library may
+implement itself in modules and publish only headers, and only its author can
+state which it means.
+
+| Condition | Reported by | Consequence stated |
+|---|---|---|
+| a `lib` target exports modules and has no lib root | `mcpp build`, for the package being built | `mcpp pack` publishes the library without a module interface |
+| exported modules that the packed form does not ship | `mcpp pack`, naming each module | a consumer of the packed form cannot import them |
+| the package being built imports a module of a dependency that has a lib root, outside its public modules; the dependency is not a member of the package's own workspace, whose members are built from source with it | `mcpp build`, naming the module and the public ones | the build succeeds from source and fails against the packed form |
+
 ## The compatibility tag
 
 Every artifact records the toolchain it was built for: