docs: publishing a workspace member, the index-archive member, CHANGELOG 2026.9.25.1, SPEC-004 criteria 13-14

Author: speak-agent

.agents/docs/2026-09-25-issue-690-implementation-plan.md

@@ -73,10 +73,10 @@ Each angle names the property it requires and the evidence that shows it.
 
 ## 5. Release chain
 
-1. PR in `mcpp-community/mcpp` with the version 2026.9.25.1 in `mcpp.toml` and `modules/versioning/src/version.cppm`. All required checks green. Squash merge.
+1. PR in `mcpp-community/mcpp` with the version 2026.9.25.1 in `mcpp.toml` and `modules/versioning/src/version.cppm`, and the internal xlings pin at the latest xlings release (2026.9.20.1). All required checks green. Squash merge.
 2. `origin/main` HEAD run green.
 3. `release.yml` dispatched. Each archive is uploaded to GitCode with the local tools the moment it appears (`tools/mirror_res.sh` from xlings, GitCode leg only). GET 200 and byte comparison on both mirrors.
 4. `openxlings/xim-pkgindex` bump pull request merged. The published index artifact is read to confirm `latest`.
-5. Bootstrap pin pull request in `mcpp-community/mcpp` (`.xlings.json`). The open #689 is resolved first.
-6. `mcpp-community/mcpp-index`: CI run against the release. No package change is expected (the design's search found no package that relies on the root include broadcast). If a package fails, it is fixed in one pull request.
-7. Sandbox verification: `xlings subos use <n> --sandbox --cmd ...` with the CN mirror set for both xlings and mcpp inside the sandbox. It covers the #690 fixture, the git-member fixture, the F7 shadow fixture, a publish dry run of a workspace member, and a build of two representative index packages.
+5. `.xlings.json` (the mcpp that builds mcpp) is not moved: review of 2026-09-25 asked for no separate bootstrap pull request unless a build needs it.
+6. `mcpp-community/mcpp-index`: one pull request that moves its CI pins to 2026.9.25.1, which runs every member on every platform against the release. Before the release, 16 members were run locally with the candidate binary (all passed), and no member declares `include_dirs`, so the W6 change has no consumer-side reliance to break there.
+7. Sandbox verification: `.agents/docs/2026-09-25-issue-690-verify.sh` in `xlings subos use <n> --sandbox --cmd ...`, with the CN mirror set for both xlings and mcpp inside the sandbox, and the same script against 2026.9.24.1 as the control.

.agents/docs/2026-09-25-issue-690-workspace-build-inheritance-consistency.md

@@ -75,6 +75,8 @@ The decisions below are derived from these rules. Each rule names its source in
 
 **F10 (measured during implementation): a member reached as a dependency does not resolve its own `x.workspace = true` entries.** A sibling `lib` whose manifest says `util.workspace = true` builds under `-p lib`. Under `-p app` it fails with `dependency 'util' has SemVer constraint '' but no readable index entry for it`. The dependency load site applied only `inherit_workspace_package`, so the entry reached resolution with neither version nor path. This is the same placement defect as F1, for the third part of what a member inherits.
 
+**F11 (measured during implementation): a member inside an index package's archive does not inherit its archive's workspace.** A descriptor may point at a member manifest (`mcpp = "*/mcpp/cairo/mcpp.toml"`; 22 installed index packages on the measuring machine have a workspace root in their archive). The resolver loaded that manifest as a stand-alone file, so a member that omits `version` was refused and `[workspace.build]` was ignored, while the same commit consumed through `git` inherits (D1). None of the 22 installed archives declares `[workspace.package]`, `[workspace.build]` or `[workspace.dependencies]`, so applying the inheritance changes no existing package. It is applied through the same function as the sibling and git cases, searching no higher than the install root (e2e 774).
+
 **F8 (reasoned): the F1 dependency's cache key records a define its compile does not carry.** `cache_key.cppm:534` reads `pkg.manifest.buildConfig.defines`, which retains the unfolded entries.
 
 Root cause: the build half of inheritance runs inside the snapshot, after the fold.

CHANGELOG.md

@@ -3,6 +3,81 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.9.25.1] - 2026-09-25
+
+### 工作空间成员在每种位置上以相同方式编译(#690)
+
+`[workspace.build]` 的继承此前在把清单固定进构建图的那一步执行,晚于 `defines` 的展开。
+作为兄弟成员 `path` 依赖被编译的成员因此收不到工作空间的 `defines`(#690 报告的情形),
+而被命令选中的根成员收到两份工作空间的 `cflags`、`cxxflags` 与 `ldflags`。现在成员在自己的
+加载处继承,顺序与根包相同:先继承,再合并条件节,最后展开 `defines`;固定进构建图的一步只读取
+结果,遇到未展开的 `defines` 时报告内部错误。
+
+同一处还补上了两件同形的缺口:
+
+- 作为依赖出现的成员解析自己的 `x.workspace = true` 条目。此前该条目以既无版本也无路径的形式
+  进入解析,报出的是「no readable index entry」。
+- 通过 `git` 引用的、托管在 git 上的工作空间的成员,除 `[workspace.package]` 外,也继承所在仓库
+  的 `[workspace.build]` 与 `[workspace.dependencies]`,相对路径以仓库根为锚点。同一个提交在它
+  自己的检出中与在使用方的依赖图中以相同方式编译。
+- 索引描述符以 `mcpp = "<子目录>/mcpp.toml"` 指向归档内的成员时,该成员以同样方式取得归档中的
+  工作空间;在归档内查找工作空间根不越出该版本的安装根。本机已安装的 22 个带工作空间根的索引包
+  都没有声明可继承的表,这一变化不改变任何现有包。
+
+`[workspace.build] ios_deployment_target` 此前被解析、被继承,却被已知键检查拒绝;可继承键现在
+只在一张表里陈述,解析、已知键检查与报错文本都取自这张表。
+
+### `defines` 按宏名构成集合
+
+`defines` 的条目按包接收它们的顺序合并:`[workspace.build]`、包自己的 `[build]`、命中的
+`[target.<selector>.build]`。同一宏名的后一个条目在原位替换前一个,条目 `!NAME` 移除该宏名,
+每个宏名只以一个 `-D` 词到达编译器。成员因此可以覆盖或移除继承来的宏,而不再产生重定义诊断
+(`-Werror` 下是错误)。`defines` 条目同样取代同一个包的 `cflags`、`cxxflags` 中同名的 `-D` 词。
+更早的 mcpp 会把 `!NAME` 作为 `-D!NAME` 交给编译器,使用它的包需要 mcpp 2026.9.25.1 或更新版本。
+
+### 使用方的头文件目录不再进入依赖
+
+根包的 `include_dirs` 与 `include_dirs_after`(包括 `private_include_dirs`)此前被写进
+`build.ninja` 的文件级编译标志,图中每个编译单元都读到它们:根包目录中与系统头或依赖头同名的
+文件会在依赖内部遮蔽它们。依赖缓存键不含这些目录,于是按一个工程的根包头文件编译出的依赖对象
+会被另一个无关工程取用(实测:`compat.cjson` 的 `cJSON_Compare(1.0, 1.2)` 在未写任何头文件的
+工程中答 1)。现在每个编译单元只收到自己的包的目录,以及它的依赖公开的目录;根包自己的编译单元
+中每个目录只出现一次。
+
+**行为变化。** 依赖若曾依靠使用方的头文件目录才能编译,现在报告缺少头文件;mcpp 在编译器报错
+之后指出该头文件所在的使用方目录。依赖需要通过自己的 `include_dirs` 或它的某个依赖找到头文件。
+依赖缓存的 epoch 由 3 升为 4,升级后首次构建重建一次依赖缓存,不需要任何操作。
+
+### 成员清单只有一种读法
+
+`mcpp publish`、`mcpp pack`、`mcpp emit xpkg`、`mcpp toolchain list`、`mcpp sbom`、`mcpp index list`/`update`、
+`mcpp update` 的索引刷新、快路径的身份判定与测试发现,此前直接读取成员目录中的原始清单:省略
+`version` 的成员被拒绝,未写 `[toolchain]` 的成员在 `toolchain list` 中显示全局默认工具链,而同一
+目录下的 `mcpp build` 用的是工作空间的工具链。现在它们与 `prepare_build` 经同一个函数读取继承后的
+清单。
+
+### 工作空间成员的发布形态自包含
+
+在成员目录中执行 `mcpp publish` 或 `mcpp emit xpkg` 时,归档只包含成员自己的目录,此前其中的
+`mcpp.toml` 原样照搬:继承的 `version`、`[build]` 标志不在其中,兄弟成员之间的 `path` 依赖原样保留
+而使用方无法解析,描述符的 `deps` 静默略去这些依赖。现在发布的清单是归一化后的:继承来的值被写出,
+`x.workspace = true` 条目取得解析后的来源,兄弟依赖以版本依赖发布,原清单以 `mcpp.toml.orig` 保留,
+归一化后的文件同时写到 `target/dist/<name>-<version>.mcpp.toml`。归档由 git 对象按提交日期构建,
+两次运行逐字节相同。不带 `version` 的兄弟 `path` 依赖、包外非成员的 `path` 依赖、位于成员目录之外的
+继承头文件目录会被拒绝,报错给出应写的内容。不是工作空间成员的包与此前一样原样归档。
+归一化后的清单只使用 2026.9.24.1 已接受的键,实测该版本的客户端可以构建它。
+
+### xlings 2026.9.20.1
+
+内置的 xlings 由 2026.9.16.1 升为 2026.9.20.1(openxlings/xlings#610):项目 subos 中执行的命令
+不再从项目的 subos 读取全局工作空间并据此删除全局 shim;下载失败的安装不再报告 `installed`。
+
+### 测试基础设施
+
+e2e 辅助脚本 `_inherit_toolchain.sh` 改为按版本链接开发者的载荷。此前它链接整个包目录,测试
+新装的版本穿过链接写进开发者的 `~/.mcpp`,链接脚本指向测试结束后即被删除的临时目录(#293 的
+第二种形态;实测 `31_transitive_deps.sh` 写出了这样的 `xim-x-glibc/2.44.3`)。
+
 ## [2026.9.24.1] - 2026-09-24
 
 ### MSVC ABI 上的 toolset:只选一次,可以指定,记录在案

docs/07-workspace.md

@@ -408,7 +408,11 @@ member inherits `[workspace.package]` as it does here (mcpp 2026.9.16.1+; see
 [05 — Dependencies](05-dependencies.md)). It also inherits its repository's
 `[workspace.build]` and resolves its `x.workspace = true` entries against that
 repository's `[workspace.dependencies]` (2026.9.25.1+), so the same commit
-compiles the same way in its own checkout and in a consumer's graph.
+compiles the same way in its own checkout and in a consumer's graph. A member
+that an index descriptor points at inside a tag tarball receives the tarball's
+workspace in the same way. Publishing a member with `mcpp publish` writes the
+inherited values into the published manifest
+([11 — Publishing a Library](11-publishing-a-library.md)).
 
 ## 7. Relationship to C++ Modules
 

docs/11-publishing-a-library.md

@@ -142,6 +142,38 @@ mcpp's build sandbox is network-isolated, so `file://` and
 seeded one is the copy that will still be there when the publish silently
 failed.
 
+## Publishing a workspace member *(mcpp 2026.9.25.1+)*
+
+A member's manifest may leave `version`, `[build]` flags and `x.workspace = true`
+entries to its workspace ([07](07-workspace.md) §4.1). Both publishing routes
+keep that working.
+
+- **The descriptor points into the repository's tag tarball**
+  (`mcpp = "*/libs/http/mcpp.toml"`). The consumer reads the member's manifest
+  from the tarball and applies the workspace root the tarball contains, as a
+  `git` consumer does. The manifest is published as written.
+- **`mcpp publish` or `mcpp emit xpkg` inside the member.** The archive contains
+  only the member's directory, so its `mcpp.toml` is normalised: the values the
+  member inherits are written out, `x.workspace = true` entries receive their
+  resolved source, and a dependency on a sibling member is published as a
+  version dependency. The manifest as written is kept beside it as
+  `mcpp.toml.orig`, and the normalised file is also written to
+  `target/dist/<name>-<version>.mcpp.toml` for review. The archive is built from
+  git objects with the commit's dates, so two runs produce the same bytes. A
+  package that is not a workspace member is archived exactly as before.
+
+A sibling dependency states the version it is published under:
+
+```toml
+[dependencies]
+"acme.util" = { path = "../util", version = "0.3.0" }   # path for development, version for consumers
+```
+
+`mcpp publish` refuses a sibling dependency without `version` and names the
+member's version and the line to write. It refuses a `path` dependency outside
+the package that is not a workspace member, and an inherited include directory
+outside the member's directory, because the archive contains neither.
+
 ## Manifest keys that need a version floor
 
 Most `[build]` keys degrade cleanly on an older mcpp: it warns that the key is
@@ -169,4 +201,5 @@ re-refreshing the index looking for it.
 - [ ] `publish-artifact.yml` succeeded
 - [ ] cold resolve (seeded copy deleted) downloads and compiles it
 - [ ] consumers bumped
+- [ ] a workspace member: the normalised `target/dist/<name>-<version>.mcpp.toml` reviewed
 

docs/specs/manifest-semantics.md

@@ -344,6 +344,15 @@ feature-deps          feature-xlings         ← 限定词是门
     的编译命令在两个仅 include 设置不同的根包下相同;根包自己的编译单元中每个根包目录
     恰好出现一次;依赖因此找不到头文件时,报错之后指出消费者目录
     (`tests/e2e/765_a_consumer_include_directory_stays_in_the_consumer.sh`)。
+13. §9 第 1 条索引归档一种情况的判据:描述符指向归档内一个省略 `version` 的成员时,该成员
+    取得归档工作空间的版本与 `defines`(`tests/e2e/774_an_index_member_inherits_its_archive_workspace.sh`)。
+    第 5 条的判据:成员目录内的 `emit xpkg`、`publish --dry-run`、`toolchain list` 读取继承后的
+    清单(`tests/e2e/773_commands_outside_the_build_read_the_effective_manifest.sh`)。
+14. §9 第 7 条的判据:发布归档中的清单写出继承来的 `version`、`license` 与 `cxxflags`,兄弟边
+    以版本边出现且描述符的 `deps` 列出它,原清单以 `mcpp.toml.orig` 保留;归档的使用方在新旧两个
+    客户端上都能构建;两次发布的归档逐字节相同;缺少 `version` 的兄弟 `path` 边被拒绝且报错给出
+    应写的一行;无需修改的包的归档与此前逐字节相同
+    (`tests/e2e/772_a_published_member_is_self_contained.sh`)。
 
 ## 8. 编译 flag 列表的元素
 
@@ -385,9 +394,10 @@ feature、`[profile.<n>]`、`[target.<selector>.build]`、xpkg 描述符,以及
 ## 9. 工作空间继承与构建需求的作用域
 
 1. 工作空间成员**必须**恰好接收一次 `[workspace.package]`、`[workspace.build]` 与
-   `x.workspace = true` 条目的继承,无论它是命令构建的包、另一个成员的 `path` 依赖,
-   还是通过 `git` 引用的、托管在 git 上的工作空间的成员。后一种情况按该成员所在仓库的
-   工作空间根继承,相对路径以该仓库的根为锚点。
+   `x.workspace = true` 条目的继承,无论它是命令构建的包、另一个成员的 `path` 依赖、
+   通过 `git` 引用的托管在 git 上的工作空间的成员,还是索引包归档内的成员(描述符的
+   `mcpp` 字段指向该成员的清单)。后两种情况按该成员所在仓库或归档的工作空间根继承,
+   相对路径以该根为锚点;在归档内查找工作空间根时**禁止**越出该版本的安装根。
 2. 向量按工作空间、成员、命中的 `[target.<selector>.build]` 的顺序追加;`defines` 按
    §8 的集合语义合并。标量仅在成员未**声明**该键时取工作空间的值。
 3. 继承**必须**在 `defines` 展开之前、在清单被固定进构建图之前完成。实现**必须**拒绝
@@ -414,4 +424,4 @@ feature、`[profile.<n>]`、`[target.<selector>.build]`、xpkg 描述符,以及
 | 1.3 | 2026-09-14 | 条件依赖声明替换同一身份的无条件声明,`targets.<name>` 成为可条件化的 section,不读取的 section 必须报出(mcpp 2026.9.14.2):新增 §3.1.1 与 §7 第 8 条判据。 |
 | 1.4 | 2026-09-15 | 库目标的默认链接形态 `linkage`(mcpp 2026.9.15.2):§3.1.1 补默认值的语义、优先顺序与拒绝条件;§7 补第 9 条判据。 |
 | 1.5 | 2026-09-17 | 编译 flag 列表元素的读法(mcpp 2026.9.17.1,#655):新增 §8 与 §7 第 10 条判据。 |
-| 1.6 | 2026-09-25 | 工作空间继承与构建需求的作用域(mcpp 2026.9.25.1,#690):§8 补 `defines` 的集合语义;新增 §9 与 §7 第 11、12 条判据。 |
+| 1.6 | 2026-09-25 | 工作空间继承与构建需求的作用域(mcpp 2026.9.25.1,#690):§8 补 `defines` 的集合语义;新增 §9 与 §7 第 11 至 14 条判据。 |

docs/zh/07-workspace.md

@@ -391,7 +391,9 @@ myproject/
 `[workspace.package]`（mcpp 2026.9.16.1+；见 [05 —— 依赖](05-dependencies.md)）。
 它还继承所在仓库的 `[workspace.build]`，并按该仓库的 `[workspace.dependencies]`
 解析自己的 `x.workspace = true` 条目（2026.9.25.1+），因此同一个提交在它自己的
-检出中与在使用方的依赖图中以相同方式编译。
+检出中与在使用方的依赖图中以相同方式编译。索引描述符指向 tag tarball 内的成员时，
+该成员以同样方式取得 tarball 中的工作空间。用 `mcpp publish` 发布成员时，继承来的值
+被写入发布的清单（[11 —— 发布库](11-publishing-a-library.md)）。
 
 ## 7. 与 C++ 模块的关系
 

docs/zh/11-publishing-a-library.md

@@ -130,6 +130,32 @@ mcpp 的构建沙箱与网络隔离，`file://` 和 `http://127.0.0.1` 形式的
 **在相信「真的能用」之前，先删掉播种的那一份。** 播种出来的 0.0.48 与已发布的
 0.0.48 对构建而言毫无区别，而当发布实际上已悄悄失败时，留在那里的正是播种的那一份。
 
+## 发布工作空间成员 *(mcpp 2026.9.25.1+)*
+
+成员的清单可以把 `version`、`[build]` 标志与 `x.workspace = true` 条目交给工作空间
+提供（[07](07-workspace.md) §4.1）。两种发布方式都保留这一点。
+
+- **描述符指向仓库 tag tarball 中的成员**（`mcpp = "*/libs/http/mcpp.toml"`）。使用方
+  从 tarball 中读取成员的清单，并应用 tarball 所含的工作空间根，与通过 `git` 引用时
+  相同。清单按原样发布。
+- **在成员目录中执行 `mcpp publish` 或 `mcpp emit xpkg`。** 归档只包含成员自己的目录，
+  因此其中的 `mcpp.toml` 被归一化：成员继承的值被写出，`x.workspace = true` 条目取得
+  解析后的来源，对兄弟成员的依赖以版本依赖发布。原样的清单以 `mcpp.toml.orig` 保留在
+  旁边，归一化后的文件同时写到 `target/dist/<name>-<version>.mcpp.toml` 供审阅。归档由
+  git 对象按提交的日期构建，两次运行产生相同的字节。不是工作空间成员的包与此前一样
+  原样归档。
+
+兄弟依赖写出它发布时的版本：
+
+```toml
+[dependencies]
+"acme.util" = { path = "../util", version = "0.3.0" }   # path 用于开发，version 用于使用方
+```
+
+`mcpp publish` 拒绝不带 `version` 的兄弟依赖，并给出该成员的版本和应写的一行。它同样
+拒绝包外、且不是工作空间成员的 `path` 依赖，以及位于成员目录之外的继承头文件目录，因为
+归档中二者都不存在。
+
 ## 需要版本下限的 manifest 键
 
 多数 `[build]` 键在较旧的 mcpp 上会干净地降级：警告该键不受支持、忽略它，构建要么
@@ -153,4 +179,5 @@ mcpp 的构建沙箱与网络隔离，`file://` 和 `http://127.0.0.1` 形式的
 - [ ] `publish-artifact.yml` 已成功
 - [ ] 冷解析（已删掉播种拷贝）能下载并编译
 - [ ] 消费方已升版本
+- [ ] 工作空间成员：已审阅归一化后的 `target/dist/<name>-<version>.mcpp.toml`
 </content>