feat(build): a source glob may carry the accel it is for, and the build narrows to it

`[build] sources` accepts `{ glob = "...", accel = "..." }` entries. The glob
joins the plain list, so every reader keeps working; the constraint is
resolved in prepare after feature application. A constrained glob that
matches nothing is refused, naming it. Under a build that asks for no
accelerator the glob is excluded through the same `!` mechanism feature gates
use, which is how one project yields its CPU-only variant. Under a build
that targets something the constraint is not within, the build is refused
naming the glob and both sides (`accel-mismatch`). Device-kind files the
effective set matches reach the build program as MCPP_DEVICE_SOURCES; the
engine has no compile rule for them and the rule package turns each into an
action. Unit tests cover the table form and its refusals; e2e 606 measures
the four outcomes with a backend nothing knows.

Author: speak-agent

docs/05-mcpp-toml.md

@@ -215,6 +215,18 @@ the package/feature boundary, not on an individual target.
 > mcpp 2026.8.18.1 the two were byte-identical, so there was no spelling for
 > "nothing" and any file left under `src/` was swept in.
 
+> **A `sources` entry may carry the accelerator it is for** (2026.9.6+):
+> `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`. The glob
+> joins the list like any other; the constraint decides whether it applies to a
+> given build. It must match at least one file (an empty match is refused: it
+> would leave nothing to compile for that device and say so only at the link).
+> Under `--no-accel` the glob is left out, which is how one project yields its
+> CPU-only variant. Under an `--accel` that does not cover the constraint the
+> build is refused naming both (`accel-mismatch`). Device-kind files (`.cu`,
+> `.hip`) the effective set matches are never compiled by the engine; they
+> reach the build program as `MCPP_DEVICE_SOURCES`, where the rule package the
+> project imports turns each into an `mcpp::action`.
+
 ```toml
 [build]
 sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # Source globs (default: src/**/*.{cppm,cpp,cc,c,S,s,asm})

docs/07-build-mcpp.md

@@ -533,6 +533,7 @@ The running program receives the build context as `MCPP_*` variables
 | `MCPP_HOST` | `mcpp::host()` | the host triple |
 | `MCPP_PROFILE` | `mcpp::profile()` | effective profile name (`dev`/`release`/…) |
 | `MCPP_ACCEL` *(2026.9.6+)* | `mcpp::accel()` | the device axis of this build, resolved — `--accel` / `--no-accel` over `[build] accel` — in the wire form `cuda12.9+{sm_89} ptx>=89`; empty when the build asks for no accelerator. A rule package derives its own flags (`-gencode`, `--offload-arch`) from it, so the architecture set is written once, in the manifest. The same value feeds the `cfg(accelerator = "…")` layer key |
+| `MCPP_DEVICE_SOURCES` *(2026.9.6+)* | `mcpp::device_sources()` | the device-kind sources (`.cu`, `.hip`, …) the package's effective `sources` match, package-root-relative, one per line; empty when there are none. The engine compiles none of them — the rule package this program imports turns each into an `mcpp::action`. Already narrowed: a `{ glob, accel }` entry the build does not cover contributes nothing, so `--no-accel` yields an empty list |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | a writable scratch/output dir owned by mcpp |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | the package root (= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | set to `1` per active feature (same `<NAME>` sanitization as the `MCPP_FEATURE_` compile macro) |

docs/11-machine-output.md

@@ -379,6 +379,7 @@ a program classifying the outcome reads `reason`:
 | `layer-ordering` | the five layers do not stack |
 | `exclusive-capability` | two packages provide one capability and at least one declared it exclusive |
 | `version-floor-unmet` | a package requires more of the machine than the machine was declared to have |
+| `accel-mismatch` | a `[build] sources` entry is constrained to a device set this build does not cover |
 | `other` | a refusal whose branch has not been given a token yet |
 
 ⚠️ **Exit 0 whenever the question was answered, including "refused".** "Would

docs/zh/05-mcpp-toml.md

@@ -201,6 +201,15 @@ mcpp 刻意不在一次构建里把同一个共享源编译成两份:一个源
 > `src/` 下剩下的任何文件都会被扫进来。
 
 
+> **`sources` 的条目可以带上它所面向的加速器**(2026.9.6+):
+> `{ glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }`。glob 与其它条目一样
+> 进入列表;约束决定它是否适用于某一次构建。它必须至少匹配一个文件(空匹配会被拒绝:
+> 那会让这个设备无东西可编,而只在链接时才说话)。`--no-accel` 下该 glob 被排除,
+> 一个工程由此产出它的 CPU-only 变体。`--accel` 未覆盖该约束时构建被拒并给出两侧
+> (`accel-mismatch`)。有效集合匹配到的设备类源文件(`.cu`、`.hip`)引擎从不编译;
+> 它们以 `MCPP_DEVICE_SOURCES` 到达构建程序,由工程引入的规则包把每一个变成一条
+> `mcpp::action`。
+
 ```toml
 [build]
 sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # 源文件 glob(默认: src/**/*.{cppm,cpp,cc,c,S,s,asm})

docs/zh/07-build-mcpp.md

@@ -463,6 +463,7 @@ mcpp 会把它自己构建时用的**同一份** std 模块暂存过来,缓存
 | `MCPP_HOST` | `mcpp::host()` | 宿主三元组 |
 | `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名(`dev`/`release`/…) |
 | `MCPP_ACCEL` *(2026.9.6+)* | `mcpp::accel()` | 本次构建的设备轴,已解析 —— `--accel` / `--no-accel` 优先于 `[build] accel` —— 线上形态 `cuda12.9+{sm_89} ptx>=89`;不要加速器时为空串。规则包从它推导自己的开关(`-gencode`、`--offload-arch`),架构集合因此只在 manifest 写一次。同一个值也喂给 `cfg(accelerator = "…")` 这个 layer 键 |
+| `MCPP_DEVICE_SOURCES` *(2026.9.6+)* | `mcpp::device_sources()` | 本包有效 `sources` 匹配到的设备类源文件(`.cu`、`.hip`…),相对包根,一行一个;没有时为空串。引擎一个都不编译 —— 由本程序引入的规则包把每一个变成一条 `mcpp::action`。已经过收窄:构建未覆盖的 `{ glob, accel }` 条目贡献为空,因此 `--no-accel` 得到空列表 |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | mcpp 提供的可写输出/暂存目录 |
 | `MCPP_MANIFEST_DIR` | `mcpp::manifest_dir()` | 包根(= CWD) |
 | `MCPP_FEATURE_<NAME>` | `mcpp::has_feature("name")` | 每个活跃 feature 置 `1`(`<NAME>` 消毒规则与 `MCPP_FEATURE_` 编译宏一致) |

docs/zh/11-machine-output.md

@@ -333,6 +333,7 @@ mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
 | `layer-ordering` | 五层叠不起来 |
 | `exclusive-capability` | 一个能力有多个提供者,而其中至少一个声明了独占 |
 | `version-floor-unmet` | 一个包对机器的要求高于机器被声明拥有的 |
+| `accel-mismatch` | 一条 `[build] sources` 条目被约束到本次构建未覆盖的设备集合 |
 | `other` | 一处还没有被命名的拒绝分支 |
 
 ⚠️ **只要问题被回答了就退 0,包括答案是「拒绝」。** 「它能不能构建,不能的话

modules/manifest/src/toml.cppm

@@ -485,6 +485,14 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     // find_disallowed_array_of_tables above.
     static constexpr std::string_view kAllowedArraysOfTables[] = {
         "build.flags",
+        // A `sources` list whose every entry is a table (`[{ glob, accel }]`)
+        // has the same Value shape as `[[build.sources]]`; the reader
+        // type-checks every entry, so nothing is silently taken. The
+        // conditional axis is allowlisted for the same reason: its reader
+        // refuses a table entry with a message that says where it belongs,
+        // which this guard's generic sentence would pre-empt.
+        "build.sources",
+        "target.*.build.sources",
         "features.*.flags",   // #253 — the middle segment is the feature name
         "target.*.build.flags",  // #258 — middle segment is the cfg predicate
         "runtime.requirements",
@@ -594,8 +602,48 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     // mean "compile nothing", and only the key's existence can say that (see
     // BuildConfig::sourcesDeclared). Set from either spelling, because the
     // legacy one has to be able to express it too.
-    if (auto v = doc->get_string_array("build.sources")) {
-        m.buildConfig.sources = *v;
+    // A mixed list: plain globs, and tables that carry a constraint. Read
+    // element by element rather than through get_string_array, which answers
+    // "not a string array" for a list with one table in it -- and then the
+    // key would count as absent, the default glob would apply, and the
+    // constrained entry would vanish without a word.
+    if (auto* sv = doc->get("build.sources")) {
+        if (!sv->is_array()) {
+            return std::unexpected(error(origin,
+                "[build].sources must be an array of globs and/or inline tables "
+                "({ glob = \"...\", accel = \"...\" })"));
+        }
+        for (auto& ev : sv->as_array()) {
+            if (ev.is_string()) { m.buildConfig.sources.push_back(ev.as_string()); continue; }
+            if (!ev.is_table()) {
+                return std::unexpected(error(origin,
+                    "[build].sources entries must be strings or inline tables "
+                    "with a `glob` key"));
+            }
+            mcpp::manifest::BuildConfig::SourceConstraint sc;
+            for (auto& [k, v] : ev.as_table()) {
+                bool ok = false;
+                if      (k == "glob")  { ok = v.is_string(); if (ok) sc.glob  = v.as_string(); }
+                else if (k == "accel") { ok = v.is_string(); if (ok) sc.accel = v.as_string(); }
+                if (!ok) {
+                    return std::unexpected(error(origin, std::format(
+                        "[build].sources: invalid key '{}' in a table entry "
+                        "(expected glob = \"...\" and optionally accel = \"...\")", k)));
+                }
+            }
+            if (sc.glob.empty()) {
+                return std::unexpected(error(origin,
+                    "[build].sources: a table entry is missing its `glob` key"));
+            }
+            if (sc.glob.starts_with("!")) {
+                return std::unexpected(error(origin, std::format(
+                    "[build].sources: a constrained entry cannot be an exclusion "
+                    "('{}'); write the exclusion as a plain string", sc.glob)));
+            }
+            m.buildConfig.sources.push_back(sc.glob);
+            if (!sc.accel.empty())
+                m.buildConfig.sourceConstraints.push_back(std::move(sc));
+        }
         m.buildConfig.sourcesDeclared = true;
     }
     if (auto v = doc->get_string_array("modules.sources")) {
@@ -2451,6 +2499,17 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
                 read_list("cflags",   cc.inputs.cflags);
                 read_list("cxxflags", cc.inputs.cxxflags);
                 read_list("ldflags",  cc.inputs.ldflags);
+                // A constrained entry (`{ glob, accel }`) is refused here rather
+                // than skipped: read_list keeps strings only, and a table that
+                // silently vanished would be a device glob nobody ever narrowed.
+                if (auto f = bt.find("sources"); f != bt.end() && f->second.is_array())
+                    for (auto& v : f->second.as_array())
+                        if (!v.is_string()) {
+                            return std::unexpected(error(origin,
+                                "[target.'cfg(...)'.build].sources entries must be "
+                                "plain globs; a constrained entry ({ glob, accel }) "
+                                "belongs in [build].sources"));
+                        }
                 read_list("sources",  cc.inputs.sources);
                 // #296: package-level macros are a build input like any other,
                 // so the cfg axis carries them too — a platform-only macro

modules/manifest/src/types.cppm

@@ -550,6 +550,26 @@ struct BuildConfig : BuildInputs {
     // the "main" feature) without it being linked by default — see
     // .agents/docs/2026-06-25-gtest-main-feature-and-add-dev-design.md.
     std::map<std::string, std::vector<std::string>> featureSources;
+    // `[build] sources` entries written as a table:
+    //
+    //     sources = ["src/**/*.cppm", { glob = "src/kernels/**/*.cu", accel = "cuda12.9+{sm_89}" }]
+    //
+    // The glob ALSO appears in `sources`, so every reader that walks the plain
+    // list sees it; this carries the constraint that decides whether it
+    // applies to a given build. Resolved in prepare_build: the glob must match
+    // at least one file (an empty match is a typo, not a no-op); when the
+    // build asks for no accelerator the glob is excluded, which is how
+    // `--no-accel` yields the CPU-only variant of a project; and when it does
+    // ask for one, the constraint must lie within what the build targets, or
+    // the build is refused naming both. Device-kind files the effective source
+    // set matches are handed to the package's build program
+    // (MCPP_DEVICE_SOURCES) rather than compiled by the engine, which has no
+    // rule for them: that is the rule package's business.
+    struct SourceConstraint {
+        std::string glob;
+        std::string accel;    // wire form, the mcpp.pack.abi_tag grammar
+    };
+    std::vector<SourceConstraint> sourceConstraints;
     // feature name → package-owned preprocessor defines (e.g. "-DEIGEN_USE_BLAS").
     // Feature System v2 Stage 1: when the feature is active these are appended to
     // the package's compile flags alongside the automatic -DMCPP_FEATURE_<NAME>

src/build/build_program.cppm

@@ -84,6 +84,13 @@ struct BuildProgramEnv {
     // (`-gencode`, `--offload-arch`) from here and the architecture set is
     // written once, in the manifest, and never again in a build program.
     std::string accel;
+    // The device-kind sources (`.cu`, `.hip`, ...) this package's effective
+    // source set matches, package-root-relative with `/` separators, one per
+    // line. The engine has no compile rule for them and hands the list to the
+    // build program, where the rule package the package imports turns each
+    // one into an `mcpp::action`. Already narrowed: a glob whose `accel`
+    // constraint the build does not satisfy contributes nothing.
+    std::vector<std::string> deviceSources;
     // Artifact home (bin/cache/out). Empty → <root>/target/.build-mcpp (the
     // root-project default). Dependencies MUST point this into the CONSUMING
     // project's tree — a registry package root is shared and may be read-only.
@@ -434,6 +441,14 @@ contract_env(const fs::path& root, const fs::path& outDir, const BuildProgramEnv
     e.emplace_back("MCPP_TARGET_LIBC", env.targetLibc);
     e.emplace_back("MCPP_PROFILE", env.profile);
     e.emplace_back("MCPP_ACCEL", env.accel);
+    {
+        std::string joined;
+        for (auto const& d : env.deviceSources) {
+            if (!joined.empty()) joined += '\n';
+            joined += d;
+        }
+        e.emplace_back("MCPP_DEVICE_SOURCES", joined);
+    }
     e.emplace_back("MCPP_OUT_DIR", outDir.string());
     e.emplace_back("MCPP_MANIFEST_DIR", root.string());
     std::string csv;

src/build/hostprogram.cppm

@@ -243,6 +243,13 @@ inline const char* profile()                      { return env_or("MCPP_PROFILE"
 // means beyond "backend, version, architectures, floor" is the package's
 // business: the engine never learns what `sm_89` is.
 inline const char* accel()                        { return env_or("MCPP_ACCEL"); }
+// The device-kind sources (`.cu`, `.hip`, ...) this package's `sources` match
+// under the current accel, package-root-relative, one per line, "" when there
+// are none. The engine compiles none of them; the rule package this program
+// imports turns each into an `mcpp::action`. Already narrowed: a glob written
+// as `{ glob = "...", accel = "..." }` whose constraint the build does not
+// satisfy contributes nothing, so `--no-accel` yields an empty list.
+inline const char* device_sources()               { return env_or("MCPP_DEVICE_SOURCES"); }
 inline const char* out_dir()                      { return env_or("MCPP_OUT_DIR"); }
 
 // Where the TOOLCHAIN mcpp resolved for this build lives — the payload root,