xlings: one table, deps superseded, envs removed, and the install-time edge published

`[xlings]` is mcpp's surface for xlings' local project mechanism, and this
brings the manifest into line with what that mechanism has.

`[xlings.workspace]` becomes the one table. An entry names a package and the
version this project uses it at, and produces two projections: an install
address for provisioning and a resolution pin for the materialised
`.xlings.json`. The namespace may be written on the key or on the version —
`"xim:picolibc-riscv" = "1.8.12"` and `picolibc-riscv = "xim:1.8.12"` are one
entry — because both spellings already exist in the ecosystem and neither is
more natural; writing it on both halves with different values is refused, as is
naming one package twice. `""` means present with the version unconstrained,
which is the spelling an authored project file already uses. Platform keys are
xlings' own, with `macos` kept as an alias.

`deps` is superseded and still honoured, reported once with the line to write
instead. It is not refused: a refusal would reach a dependency's manifest that a
consumer pinning that package cannot edit. One package in both tables with two
versions is a hard error, because the two are provisioned in order while the
last wins the pin — install one, resolve the other.

`envs` is removed. It was materialised into the file and read by nothing: the
two `envs` structures xlings has belong to a program's own shim record and to a
SubOS's provider sections, and mcpp's run environment comes from the runtime
binding. The documentation described an effect that did not occur, which is why
this is an error rather than a warning.

`mcpp emit xpkg` writes `xpm.<platform>.deps`. Nothing emitted it before, so a
package declaring an environment had its install-time edge written by hand —
which is how riscv-virt-rt 0.3.0 shipped without the C library its own target
row named. The declaration is kept unresolved per platform for it, since a
descriptor has a block per platform and the host resolution has discarded two.

Documented: the three-row inheritance rule, which has always held and which
mcpp stated nowhere — no `subos` means the machine's environment with the
project's entries over it, a named one means isolation, and an `xlings use`
inside the project outranks both.

Verified: e2e 331 asserts on the addresses the provisioning pass names with
auto-install off, so every criterion runs on every shard with no network; it
fails at its first assertion on 2026.9.2.1. Unit: test_manifest +8. Full unit
suite 97 passed; e2e 06, 93, 130, 131, 132, 134 re-run.

Author: speak-agent

.agents/docs/2026-09-03-xlings-workspace-as-the-one-table.md

@@ -21,10 +21,11 @@ Three changes follow, and one of them is a defect rather than a design.
 1. **`workspace` becomes the one table**; `deps` is retired from the manifest.
    The two state the same thing and differ only in what mcpp then does with the
    statement, and the mechanism they map onto has one authored surface.
-2. **Provisioning moves into project scope.** mcpp calls xlings with a global
-   environment today, so the install writes into a workspace shared by every
-   mcpp project while programs resolve through the project's own layers. That
-   one argument is behind three measured symptoms.
+2. ~~Provisioning moves into project scope.~~ **Withdrawn during
+   implementation** (§3): the call site records a measurement showing that
+   project scope puts payloads in a SubOS the compiler's `--sysroot` does not
+   name. The scope stays global; what the declaration decides is unchanged,
+   because resolution reads the project's `workspace` layer either way.
 3. **`envs` is retired.** It has no reader in xlings and none in mcpp, and
    `docs/05` documents an effect it does not have.
 
@@ -201,78 +202,51 @@ silence. `[xlings]` has no unknown-key sweep — no `kKnownXlings` list exists i
 `toml.cppm` — so a removed key would be read by nobody and reported by nobody,
 which is the shape #531 exists to prevent.
 
-## 3. Change two: provisioning runs in project scope
-
-### 3.1 The defect
-
-```cpp
-mcpp::xlings::call(mcpp::config::make_xlings_env(**cfg2), "install_packages", …)
-```
-
-`prepare.cppm:3421`. `make_xlings_env` carries no `projectDir`
-(`src/config.cpp:129`), so no `XLINGS_PROJECT_DIR` reaches the child and the
-cwd walk finds nothing. The child runs in **global** scope against mcpp's
-registry home, and three symptoms follow:
-
-1. **The install's view and the shim's view disagree.** Records land in the
-   registry's global workspace; a program invoked from the project resolves
-   through the project's layers. This is the
-   `qemu-aarch64-static is not installed in this subos (_)` measured during the
-   2026.9.2.1 verification, and the reason the runner needed a
-   payload-directory lookup.
-2. **`active` is read from a workspace shared by every mcpp project** on the
-   machine, so the auto-activation decides against a state no project owns.
-3. **Forcing the switch there would let two checkouts flip each other**, which
-   is why the decline is protective in this scope rather than obstructive.
-
-### 3.2 The fix, and why nothing else is needed
-
-Call with `make_project_xlings_env(cfg, root)`. The child then runs in project
-scope: the installed set and the activation records land in the project's own
-SubOS, and the view the install writes is the view the shim reads.
-
-**No flag, and no explicit switch.** With the declaration materialised into the
-project file's `workspace`, §1's merge already makes it authoritative —
-Anonymous puts the project layer over the global one, Named does not merge the
-global one at all. `activate_requested_targets` does not fire in that situation
-and should not: the merged view already answers with the declared version.
-
-An earlier draft proposed `useAfterInstall: true` and an explicit `use_version`
-per entry. Both are withdrawn (§15).
-
-**One precondition, checked.** The scope fix works only if xlings accepts
-`<project>/.mcpp` as a project directory, and §1's discovery rule rejects any
-directory holding a `subos/`. It does not fire here: a project's SubOS lives at
-`<projectDir>/.xlings/subos/<name>`, so what would have to exist is
-`<project>/.mcpp/subos`, and nothing creates it — measured on
-`mcpplibs/riscv-virt-rt/.mcpp/`, which holds only `.xlings.json`. It is worth
-an assertion rather than a memory: anything that later writes a bare `subos/`
-under `.mcpp` would make mcpp's own project file invisible to xlings, silently
-and everywhere at once.
-
-### 3.3 Provisioning otherwise keeps its contract
-
-- The result is read, not assumed: `!called || childRc != 0`
-  (`prepare.cppm:3448`).
-- A failure is a hard build error naming the manual command.
-- The stamp is written only on success and keyed on the hash of the declared
-  set, so the merged table re-provisions once per project after the upgrade and
-  the common build performs nothing.
-- `MCPP_OFFLINE` and `MCPP_NO_AUTO_INSTALL` gate the install action, not the
-  block.
-
-### 3.4 Two consequences to write down
-
-**The project SubOS layer outranks the project manifest.** It merges last, so
-an explicit `xlings use` inside the project beats what `mcpp.toml` declares
-until the manifest is re-materialised. Defensible — an action a person took
-beats a file — but not obvious.
-
-**A declared version that was never installed already fails with the right
-words**: `"{}@{} is the version this project asks for"`
-(`src/core/xvm/shim.cpp:495`). Provisioning is what prevents it; that
-diagnostic is what happens when provisioning was skipped, and it names the
-project rather than the machine.
+## 3. Change two, withdrawn during implementation: the scope stays global
+
+The design proposed moving the provisioning call from `make_xlings_env` to
+`make_project_xlings_env`, on the reasoning that the install should write where
+the shim reads. Implementing it turned up a comment at the call site recording
+that this was tried and measured:
+
+> GLOBAL scope, and the scope is the whole point. The obvious alternative —
+> `install_packages` against `make_project_xlings_env` — installs at PROJECT
+> scope, and that measurably does not work: on a fresh `MCPP_HOME` the headers
+> land in `<proj>/.mcpp/.xlings/subos/_/usr/include` while `--sysroot` names
+> `<MCPP_HOME>/registry/subos/default`, so `#include <gbm.h>` still failed with
+> the dependency installed and declared. Two SubOS views, and the payload in
+> the one the compiler does not read.
+
+The premise the design rested on — that the install destination is chosen by
+package scope rather than by transport — is contradicted by that measurement.
+**Change two is withdrawn.** The call keeps `make_xlings_env`.
+
+### 3.1 What that leaves true, and what it leaves unsolved
+
+**The declaration still wins at resolution.** mcpp materialises
+`[xlings.workspace]` into the project file's `workspace` object, and that is a
+layer `merged_workspace` applies over the machine's (§1). So a project
+declaring a version resolves to it inside the project regardless of where the
+payload was installed. Provisioning only has to make the payload exist, which
+global scope does.
+
+**Two views still disagree about the installed set.** A payload installed into
+the registry is not in the project SubOS's `installed[]`, so a shim invoked in
+the project can resolve the declared version and still report
+`… is not installed in this subos (_)`. That is the line the 2026.9.2.1
+verification recorded, and the reason the runner resolves a program through the
+declared payload's `bin/` before consulting `PATH`.
+
+That mismatch is real and is not addressed here. It is a question about which
+environment mcpp's own `--sysroot` names — the registry SubOS today — and
+answering it means changing where mcpp points the compiler, not where it points
+an install. That is a larger change than this document, and the runner lookup
+is a working compensation for its user-visible half.
+
+**What is not done, and why it is not a gap in this change:** nothing in the
+merged table depends on the scope. `deps` and `workspace` are two projections
+of one entry either way, and the entry provisions and resolves exactly as it
+did before.
 
 ## 4. Change three: `envs` is retired
 

CHANGELOG.md

@@ -3,6 +3,54 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.9.3.1] — 2026-09-03
+
+`[xlings]` 收敛成一张表。`[xlings.workspace]` 说出工程用哪个包、用哪个版本,mcpp
+既供给它也把它物化成解析用的钉;`deps` 被取代;`envs` 移除;发布出去的描述符第一次
+带上安装期的边。
+
+设计与全部实测见
+[`.agents/docs/2026-09-03-xlings-workspace-as-the-one-table.md`](.agents/docs/2026-09-03-xlings-workspace-as-the-one-table.md)。
+
+> **一般形态比它自己的简写弱。** `docs/05` §2.13 写着 `[toolchain]` 是编译器那一项
+> 的便捷写法、`[xlings.workspace]` 是一般形态;而 `[toolchain]` 会装
+> (`resolve_xpkg_path(…, autoInstall=…)`),一般形态什么都不装。两个键说的是同一件
+> 事,差别只在 mcpp 拿这句话去做什么 —— 而它们对应的那套机制,书写面只有一个。
+
+### 变更
+
+- **`[xlings.workspace]` 成为唯一的表。** 一条条目产出两个投影:一个安装地址
+  (`[<ns>:]<target>[@<version>]`,供给用)与一份解析钉(`[<ns>:]<version>`,写进
+  `.xlings.json` 的 `workspace` 对象)。命名空间写在键上或版本上都接受——
+  `"xim:picolibc-riscv" = "1.8.12"` 与 `picolibc-riscv = "xim:1.8.12"` 是同一条,
+  写在键上必须带引号(TOML 裸键不能含冒号);两半都写且不一致是错误。`""` 表示
+  「存在即可,版本不限」,这是手写项目文件里已经在用的拼法。平台键取 xlings 自己的
+  `linux` / `macosx` / `windows` / `default`,`macos` 作为别名保留。
+
+- **`deps` 被取代,但仍然生效并被报告。** 报告里给出该写的那一行。**不拒绝**——拒绝
+  会落到依赖的 manifest 上,而钉了那个包精确版本的工程改不了它。同一个包在两张表里
+  给出两个版本则是硬错误:两者按顺序供给而后者赢得钉,接受它等于装一个、解析另一个。
+
+- **`[xlings.envs]` 移除。** 它曾被物化进 `.xlings.json` 而没有任何东西读它:
+  xlings 里两处 `envs` 分别属于某个程序的 shim 记录和某个 SubOS 的 provider 段,
+  都不是这个形状;mcpp 自己给程序的运行环境来自 runtime binding。现在这个键是错误
+  ——**一个什么都不做的键,在有东西声称它有效果时更坏**。
+
+- **发布的描述符带上 `xpm.<platform>.deps`。** 此前 `mcpp emit xpkg` 一个字都不写,
+  安装期的边只能手写进 `xpkg.lua` —— `riscv-virt-rt` 0.3.0 因此发出去时没有它自己
+  目标行指名的 C 库。声明按**未解析**的形态保留在 `workspaceByPlatform` 里,因为
+  描述符每个平台一块,而按本机解析已经丢掉了另外两个。
+
+- **`[xlings]` 的三档继承写进文档。** 不写 `subos` 就是机器的环境加上工程自己的条目;
+  写了 `subos` 就是隔离,机器那层不参与;工程内执行的 `xlings use` 压过两者。这条
+  行为一直如此,而 mcpp 此前一字未提。
+
+### 行为变化
+
+- `[xlings.envs]` 从被忽略变成硬错误。索引里没有任何包用过它。
+- `[xlings] deps` 仍然生效,但会打印一条指出替代写法的警告;`--strict` 下它是错误。
+- 同一个包在 `deps` 与 `[xlings.workspace]` 里给出不同版本,现在被拒绝。
+
 ## [2026.9.2.1] — 2026-09-02
 
 `[target.<triple>].runner` 对每一个目标生效,启动失败不再无声,`mcpp test` 把跑不起来

docs/05-mcpp-toml.md

@@ -1866,63 +1866,80 @@ built" means is the same question `--target` answers (docs/08 §7.4).
 Both are warnings, never errors: coverage is release discipline, and the person
 who can judge it is looking at the release, not at this build.
 
-### 2.13 `[xlings]` — Build Environment
+### 2.13 `[xlings]` — the project's environment
 
 ```toml
-[xlings]
-deps  = ["make@4.4", "cmake@3.28", "python@3.13"]   # host build-tools to provision
-subos = "dev"                                        # a named per-project sandbox
-
-[xlings.workspace]                                   # pin tool versions (general form of [toolchain])
-clang = "20.1.7"
+[xlings.workspace]                 # what this project's environment contains
+cmake                   = "3.28"
+picolibc-riscv          = "xim:1.8.12"     # namespace on the version
+"xim:qemu-user-aarch64" = "7.2.0"          # or on the key - quotes required
+code                    = ""               # present; version unconstrained
+llvm                    = { macosx = "20", default = "22" }
 
-[xlings.envs]                                        # env vars applied to the tool environment
-OPENBLAS_NUM_THREADS = "1"
+subos = "dev"                      # a named, isolated environment
 ```
 
-Declares the project's **build environment**, provisioned through xlings (which mcpp
-is built on). The subsection names mirror xlings' own `.xlings.json` schema **1:1**, so
-mcpp materializes them verbatim into `<project>/.mcpp/.xlings.json` (no translation
-layer): `deps` (host build-tools), `[xlings.workspace]` (tool→version pins),
-`subos` (a named sandbox), `[xlings.envs]` (env vars). Use it to declare host tools a
-build needs (`make`/`cmake`/`protoc`/…), pin tool versions per project, or set
-build-time env vars — without hand-editing `.xlings.json`. `[toolchain]` (§2.7) remains
-the ergonomic shorthand for the compiler; `[xlings.workspace]` is the general form.
+`[xlings]` is mcpp's surface for **xlings' local project mechanism**: the
+project `.xlings.json` that gives a directory its own environment. The
+subsection names and their meanings are that file's, and mcpp materializes them
+into `<project>/.mcpp/.xlings.json` with no translation layer.
 
-**Values per host platform (2026.9.2.1+).** A `deps` entry and a
-`[xlings.workspace]` value may be a table keyed by platform, the form xlings'
-own `.xlings.json` accepts for `workspace`:
+**`[xlings.workspace]` is the one table.** An entry names a package and the
+version this project uses it at. mcpp provisions it — installing it when the
+machine does not have it, mapping it when it does — and materializes it as a
+resolution pin, so the version the project named is the one its tools resolve
+to.
 
-```toml
-[xlings]
-deps = ["xim:ninja", { linux = "qemu-user-aarch64" }, { windows = "nasm", default = "yasm" }]
-
-[xlings.workspace]
-gcc  = { linux = "15.1.0" }
-llvm = { macos = "20", default = "22" }
-```
-
-The keys are `linux`, `macos`, `windows` and `default`; `macosx` is accepted as
-xlings' spelling of `macos`. mcpp resolves the table against the host it runs
-on when the manifest is loaded: the host's key wins, `default` is the fallback,
-and a table with neither declares nothing on that host — the entry is absent,
-not empty. An unknown key is an error rather than a dropped entry. The axis is
-the host operating system only; a package that exists for the OS but not for
-the architecture is still a provisioning error on that host.
-
-`subos` selects the root project's **local build/run OS environment**. If the
-key is absent, mcpp uses its initialized, release-verified `McppDefault` SubOS;
-`subos = "default"` is an explicit `NamedSubos("default")` selection. There is
-no CLI/environment override and no implicit following of xlings active/current.
-
-On Linux the selected environment also fixes the loader/libc contract, so
-`subos = "el8"` and `subos = "trixie"` can coexist and produce separately
-fingerprinted objects. A workspace root overrides member declarations during a
-workspace build. Dependency/member SubOS declarations are non-transitive: a
-library's declaration applies when it is an independent root, not when its
-sources are consumed by another root. A missing named SubOS or missing/
-incompatible runtime contract is an error, never a fallback. See
-docs/08-toolchain-internals.md §2.1.
+#### Writing an entry
+
+| Form | Means |
+|---|---|
+| `cmake = "3.28"` | that version |
+| `llvm = "22"` | the highest installed `22.*`; a version prefix resolves |
+| `code = ""` | present, version unconstrained |
+| `picolibc-riscv = "xim:1.8.12"` | from the `xim` index |
+| `"xim:picolibc-riscv" = "1.8.12"` | the same entry, namespace written on the key |
+| `llvm = { macosx = "20", default = "22" }` | per host platform |
+
+The namespace may be written on either half. Writing it on the key requires
+**quotes**, because a TOML bare key cannot contain a colon. Writing it on both
+halves with different values is an error, and so is naming one package twice
+under two spellings.
+
+Platform keys are xlings' own — `linux`, `macosx`, `windows` — plus `default`;
+`macos` is accepted as an alias. A table with no key for this host and no
+`default` declares nothing here.
+
+#### Which version a tool the project did not name resolves to
+
+| The project declares | The version comes from |
+|---|---|
+| `[xlings.workspace]`, no `subos` | the machine's environment, with the project's own entries laid over it |
+| `[xlings.workspace]` and `subos = "<name>"` | that environment's own workspace; the machine's does not apply |
+| neither | the machine's environment |
+
+The middle row is not an omission. A named environment has its own installed
+set, and carrying the machine's versions into it would name versions that are
+not there. Naming one is how a project asks for isolation; leaving it out is
+how it asks for the machine's environment with its own entries on top.
+
+An `xlings use` performed inside the project outranks this table until mcpp
+rewrites the environment, because it is the layer merged last.
+
+#### `deps`, superseded
+
+`deps = ["xim:qemu-riscv@9.2.4-1"]` is the pre-2026.9.3 spelling of the same
+statement. It is still honoured and is reported once, with the
+`[xlings.workspace]` line to write instead. It is not refused, because a
+refusal would reach a *dependency's* manifest, which a project that pinned an
+exact version of that package cannot edit.
+
+#### `envs`, removed
+
+`[xlings.envs]` was materialized into `.xlings.json` and read by nothing: a
+program's environment is declared by its own package, and an environment's by
+that environment. The key is now an error naming both. Nothing in the index
+used it.
 
 ### 2.14 Host tools from a dependency (mcpp 2026.8.5.1+)
 

docs/17-the-project-environment.md

@@ -63,6 +63,26 @@ Declaring it is what puts it there.
 the declared environment the default answer; everything else stays reachable
 behind it.
 
+### 2.1 Which version pins apply (2026.9.3+)
+
+Naming an environment also changes where a tool's version comes from. A
+project's own `[xlings.workspace]` entries always win; what differs is what
+they are laid over:
+
+| The project declares | The version of a tool it did not name comes from |
+|---|---|
+| `[xlings.workspace]`, no `subos` | the machine's environment |
+| `[xlings.workspace]` and `subos = "<name>"` | that environment's own workspace; the machine's does not apply |
+
+The second row is what isolation means. A named environment has its own
+installed set, and carrying the machine's versions into it would name versions
+that are not there — so a project that relied on the machine's tools has to
+declare them once it names an environment.
+
+An `xlings use` performed inside the project outranks both, until mcpp rewrites
+the environment: it is the layer merged last, and an action a person took
+should beat a file.
+
 ## 3. What the declaration does not decide
 
 `[xlings] deps` names packages to be present in the environment, and each one's