A rule package declares what it compiles, so a new device language costs no engine change

Two keys on a feature, and the engine holds no package name, no feature
spelling and no module name:

    [features.rules-slang]
    sources           = ["rules/slang.cppm"]
    rule_module       = "mcpp.rules.slang"
    device_extensions = [".slang"]

`device_extensions` classifies those extensions as device sources in a consumer
that activates the feature. `rule_module` is what a build program imports to
reach the rule. Two things follow.

A NEW DEVICE LANGUAGE NO LONGER TOUCHES THE ENGINE. Adding `.slang` to the
built-in table cost an engine change, a release, and a version bump in the rule
package's CI before the rule could route one file. `.slang` is removed from that
table here and `rules-slang` declares it instead; `tests/slang-consumer` builds
and runs unchanged, which is the only honest test of whether the mechanism
carries a language. The built-in list is now what mcpp knows without being told
-- a compatibility set for languages whose support shipped before the
declaration existed -- rather than a registry a sixth backend joins.

A CONSUMER WRITES ONE EDGE AND NO BUILD PROGRAM. `host-module = true` is implied
by `rule_module`, because a feature naming one has already said that is the only
way to use it. And a package with no `build.mcpp` gets the program its rules
describe written into the build directory:

    [build-dependencies.mcpp]
    plugins = { version = "0.3.0", features = ["rules-spirv"] }

is the whole declaration in `tests/spirv-zero-config`, which compiles a shader
and reaches it through a generated module. A project that writes its own
`build.mcpp` keeps it: synthesis fills an absence and never overrides.

THE FEATURE IS STILL REQUESTED BY NAME. An earlier revision derived it from the
extensions a project's sources carried, so a consumer could name the package
alone. That was withdrawn for two reasons and neither was cost. Two packages may
claim one extension -- a third-party CUDA rule is a thing someone will write --
and derivation would then guess or refuse where `features = [...]` has already
said which. And a manifest's job is to describe the build: a derived feature set
is information the file no longer states, which is worse for a reader and worse
for anything reading the manifest as context.

Which rules ran is said out loud, for the same reason the resolved toolchain is:

       Rules mcpp.rules.spirv (mcpp:plugins)

Two ordering defects were found by running it rather than by reading it. The
collection must sit between feature activation and the extension table that
narrows the constrained globs; placed after, the declared extensions arrived too
late to classify anything and the rule was handed an empty list. And the guard
on the build-program call asked whether the FILE existed while the function
asked whether a program was WANTED, which left the synthesis unreachable. Both
now ask the same question, and the comments say what the failure looked like.

Author: speak-agent

modules/manifest/src/toml.cppm

@@ -758,6 +758,40 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
                 read_str_array(ft, "provides", provs);
                 if (!reqs.empty())  m.featureRequires[fname] = std::move(reqs);
                 if (!provs.empty()) m.featureProvides[fname] = std::move(provs);
+                // The device extensions this feature's rule compiles. Normalised
+                // the same way `module_extensions` is, so `comp` and `.comp` are
+                // one entry and a consumer cannot be surprised by a missing dot.
+                std::vector<std::string> devExts;
+                read_str_array(ft, "device_extensions", devExts);
+                if (!devExts.empty()) {
+                    for (auto& e : devExts) e = mcpp::normalize_extension(e);
+                    std::erase(devExts, std::string{});
+                    if (!devExts.empty())
+                        m.featureDeviceExtensions[fname] = std::move(devExts);
+                }
+                // The module a consumer's build program imports for this rule.
+                if (auto it = ft.find("rule_module");
+                    it != ft.end() && it->second.is_string())
+                    m.featureRuleModule[fname] = it->second.as_string();
+                // The two halves of "this feature is a build rule" must arrive
+                // together. One without the other is a declaration nothing can
+                // act on, and the failure would otherwise land in a consumer's
+                // build rather than in the package that wrote it.
+                {
+                    const bool hasExts = m.featureDeviceExtensions.contains(fname);
+                    const bool hasMod  = m.featureRuleModule.contains(fname);
+                    if (hasExts != hasMod) {
+                        return std::unexpected(error(origin, std::format(
+                            "[features].{} declares `{}` without `{}`. A build rule states "
+                            "both:\n"
+                            "       `device_extensions` is what it compiles, `rule_module` is "
+                            "how a\n"
+                            "       consumer's build program reaches it.",
+                            fname,
+                            hasExts ? "device_extensions" : "rule_module",
+                            hasExts ? "rule_module" : "device_extensions")));
+                    }
+                }
                 // #253: per-feature per-glob compile flags — same entry grammar
                 // as [build].flags (shared parse_glob_flags_value), gated by
                 // this feature and folded in AFTER base globFlags at activation

modules/manifest/src/types.cppm

@@ -639,6 +639,18 @@ struct BuildConfig : BuildInputs {
     // Scoped to the declaring package — a dependency is classified by its own
     // manifest, never by its consumer's.
     std::vector<std::string>            moduleExtensions;
+    // Device extensions this package's build-dependencies declared through
+    // `[features].<f>.device_extensions`, for the features this package
+    // requested. NOT written in a manifest: filled by prepare from the
+    // resolved edges, and carried here so every site that already builds an
+    // extension table for a package gets the device axis without a second
+    // plumbing route. A package with no rule dependency leaves it empty, which
+    // is every package that has none today.
+    std::vector<std::string>            deviceExtensions;
+    // The rule modules a synthesised `build.mcpp` imports, in the order the
+    // features were collected. Filled by prepare beside `deviceExtensions`
+    // above and read only when this package has no build program of its own.
+    std::vector<std::string>            ruleModules;
     // [build] accel — which accelerator backends and device architectures this
     // build targets, in the wire form mcpp.pack.abi_tag reads. Empty means the
     // build asks for none, and then every prebuilt artifact satisfies it
@@ -1478,6 +1490,56 @@ struct Manifest {
     //  see the member there.)
     std::map<std::string, std::vector<std::string>> featureProvides; // feature → caps
     std::map<std::string, std::vector<std::string>> featureRequires; // feature → caps
+
+    // `[features].<f>.device_extensions` — the device source extensions this feature's
+    // rule compiles (mcpp 2026.9.7.1+).
+    //
+    // THE ENGINE EXPOSES THE CAPABILITY; THE PACKAGE SUPPLIES THE FACT. The key
+    // is named after `[build] module_extensions` because it is the same shape:
+    // mcpp knows what it means for a file to be a device source -- never
+    // scanned, never a BMI, compiled by something mcpp does not drive -- and
+    // does not know that `.cu` is CUDA. A rule package states which extensions
+    // it compiles, and a consumer that activates that feature gets them
+    // classified as device sources. A NEW device language therefore costs no
+    // engine change, which is what `docs/20`'s "a sixth backend is a package
+    // rather than an engine change" has claimed and, until this key, was not.
+    //
+    // NOTHING IS DERIVED FROM IT. An earlier revision also used it to ACTIVATE
+    // the matching feature, so a consumer could name the package and nothing
+    // else. That was withdrawn for two reasons, and neither was cost:
+    //
+    //   - Two packages may claim one extension. A third-party rule for `.cu`
+    //     is a thing someone will write, and derivation would then have to
+    //     guess or refuse, where `features = ["rules-cuda"]` has already said
+    //     which one.
+    //   - A manifest's job is to describe the build. A derived feature set is
+    //     absent information that has to be reconstructed by running the
+    //     build, which is worse for a reader and worse for anything reading the
+    //     manifest as context.
+    //
+    // So the feature is requested by name, as every other feature is, and this
+    // key answers only "what does that feature compile".
+    //
+    // WHICH FEATURE COMPILES AN EXTENSION IS NOT STATED SEPARATELY. It is the
+    // feature the line is written on. A second key naming the rule would be the
+    // same fact twice.
+    std::map<std::string, std::vector<std::string>> featureDeviceExtensions;
+
+    // `[features].<f>.rule_module` — the module a consumer's build program
+    // imports to reach this feature's rule, and whose `compile()` it calls.
+    //
+    // DECLARED RATHER THAN DISCOVERED, which is the trade this codebase already
+    // makes for `mcpp::action`'s `provides`/`imports` and for
+    // `[modules] scan_overrides`. The name is in the feature's own interface
+    // unit and could be scanned out of it, but the program that imports it has
+    // to be written BEFORE anything is compiled, and a build that had to scan a
+    // dependency's sources to decide what to write would order the two the
+    // wrong way round.
+    //
+    // Present exactly when `device_extensions` is: together they say "this
+    // feature is a build rule, here is what it compiles and here is how to
+    // reach it". A feature with one and not the other is refused at parse time.
+    std::map<std::string, std::string> featureRuleModule;
     // Feature System v2 Stage 2a — dependencies activated by a feature. A dep
     // declared ONLY here is optional: pulled into the resolution worklist only
     // when its feature is active (root --features or a dep spec's features=[...]).

modules/source-kind/src/source_kind.cppm

@@ -93,6 +93,24 @@ std::string_view to_string(SourceKind k);
 struct ExtensionTable {
     // Always contains the built-ins first, in their historical order.
     std::vector<std::string> moduleInterface;
+    // Device extensions a DEPENDENCY declared it compiles, through
+    // `[features].<f>.device_extensions`. Empty for a package with no rule
+    // dependency, which is every package that has none today.
+    //
+    // WHY THE PACKAGE AND NOT THIS FILE. mcpp knows what a device source IS --
+    // never scanned, never a BMI, compiled by something mcpp does not drive --
+    // and does not know that `.cu` is CUDA. The built-in list below is the set
+    // of languages the project has already shipped support for; this axis is
+    // how a NEW one arrives without an engine release, which is what makes
+    // "a sixth backend is a package rather than an engine change" true rather
+    // than aspirational. Slang measured the difference: adding it cost an
+    // engine change, a release, and a version bump in the rule package's CI
+    // before its rule could route a single file.
+    //
+    // Same shape as `moduleInterface` above, and for the same reason: built-ins
+    // are what needs no declaring, and everything else is declared by whoever
+    // knows it.
+    std::vector<std::string> device;
 };
 
 // Trim, then supply a leading dot if absent. Does NOT change case — see the
@@ -117,6 +135,15 @@ ExtensionTable builtin_extension_table();
 // validation still classifies exactly like a default one.
 ExtensionTable extension_table_for(std::span<const std::string> extras);
 
+// The same, plus device extensions a dependency declared through
+// `[features].<f>.device_extensions`. Separate parameters rather than one list
+// because the two axes are validated differently and must not be able to leak
+// into each other: a module extension the project names is checked against the
+// reserved roles, and a device extension a dependency names is added only where
+// no built-in role already claims the spelling.
+ExtensionTable extension_table_for(std::span<const std::string> moduleExtras,
+                                   std::span<const std::string> deviceExtras);
+
 // Extensions that already name a non-module role. Declaring one of these as a
 // module interface has no legitimate use and would route (say) a C file to the
 // C++ module rule, failing somewhere that names neither the file nor the key.
@@ -272,19 +299,26 @@ constexpr std::string_view kHeaderExtensions[] = { ".h", ".hpp", ".hh", ".hxx" }
 // own -- so the island is the shape Ascend already has, not one mcpp imposes.
 // `.cce` is the older spelling of the same thing and is accepted beside it.
 //
-// `.slang` is the Slang shading language, compiled by `slangc`. It is a
-// LANGUAGE rather than a second driver for GLSL -- its own module system,
-// generics, and a target set beyond SPIR-V -- which is why it has an extension
-// of its own here and a rule of its own outside.
+// `.slang` IS NOT HERE, AND ITS ABSENCE IS THE POINT.
 //
-// THIS TABLE IS WHAT DECIDES, NOT THE GLOB'S `accel` KEY. A constrained glob
-// carrying `accel = "vulkan1.2"` does not make a file a device source; this
-// list does, and a file whose extension is absent from it reaches the ordinary
-// source scan and is refused with "mcpp has no role for the extension". A rule
-// package therefore cannot introduce a device language on its own, and adding
-// one here is the engine half of doing so.
+// Slang is a language rather than a second driver for GLSL, so it needs a rule;
+// it reaches this build through `mcpp:plugins`' `rules-slang`, which declares
+// `device_extensions = [".slang"]` in its own manifest. That is the first
+// device language mcpp supports without naming it here.
+//
+// The list below is what mcpp knows WITHOUT being told: the languages whose
+// support shipped before the declaration existed. It is a compatibility set,
+// not a registry -- a new language does not join it, and `.slang` was removed
+// after the mechanism proved able to carry it, which is the only honest test of
+// whether the mechanism works.
+//
+// THIS TABLE AND THE DECLARED ONE ARE WHAT DECIDE, NOT THE GLOB'S `accel` KEY.
+// A constrained glob carrying `accel = "vulkan1.2"` does not make a file a
+// device source; membership here or in a dependency's declaration does, and a
+// file in neither reaches the ordinary source scan and is refused with "mcpp
+// has no role for the extension".
 constexpr std::string_view kDeviceExtensions[] = {
-    ".cu", ".hip", ".sycl", ".asc", ".cce", ".slang",
+    ".cu", ".hip", ".sycl", ".asc", ".cce",
     ".comp", ".vert", ".frag", ".geom", ".tesc", ".tese", ".mesh", ".task",
     ".rgen", ".rint", ".rahit", ".rchit", ".rmiss", ".rcall",
     ".glsl", ".hlsl", ".cl", ".metal",
@@ -354,6 +388,26 @@ ExtensionTable extension_table_for(std::span<const std::string> extras) {
     return t;
 }
 
+ExtensionTable extension_table_for(std::span<const std::string> moduleExtras,
+                                   std::span<const std::string> deviceExtras) {
+    auto t = extension_table_for(moduleExtras);
+    for (auto const& raw : deviceExtras) {
+        auto ext = normalize_extension(raw);
+        if (ext.empty()) continue;
+        // A declaration cannot move a file out of a role the engine already
+        // owns. `.cpp` is a C++ translation unit whatever a dependency says,
+        // and silently accepting the entry would let one package change what
+        // every source in a consumer means.
+        if (std::ranges::find(t.moduleInterface, ext) != t.moduleInterface.end()) continue;
+        if (contains(kCxxExtensions, ext) || contains(kCExtensions, ext)
+            || contains(kGasExtensions, ext) || contains(kNasmExtensions, ext)
+            || contains(kHeaderExtensions, ext)) continue;
+        if (std::ranges::find(t.device, ext) != t.device.end()) continue;
+        t.device.push_back(std::move(ext));
+    }
+    return t;
+}
+
 bool is_reserved_non_module_extension(std::string_view ext) {
     return contains(kCxxExtensions, ext)    || contains(kCExtensions, ext)
         || contains(kGasExtensions, ext)    || contains(kNasmExtensions, ext)
@@ -408,6 +462,11 @@ SourceKind classify(const std::filesystem::path& p, const ExtensionTable& t) {
     if (contains(kGasExtensions, ext))    return SourceKind::GasAsm;
     if (contains(kNasmExtensions, ext))   return SourceKind::NasmAsm;
     if (contains(kDeviceExtensions, ext)) return SourceKind::Device;
+    // A dependency's `device_extensions`. Checked AFTER the built-in roles so a
+    // rule package cannot reclassify `.cpp`; the built-ins are the engine's own
+    // vocabulary and a declaration must not be able to move a file out of it.
+    for (auto const& d : t.device)
+        if (ext == d) return SourceKind::Device;
     if (contains(kHeaderExtensions, ext)
         || contains(kDeviceHeaderExtensions, ext)) return SourceKind::Header;
     return SourceKind::Other;

src/build/build_program.cppm

@@ -134,6 +134,13 @@ struct BuildProgramEnv {
     // and an engine older than this one leaves the variable absent -- which a
     // rule reads as "header", the behaviour every consumer had before.
     bool languageModules = true;
+    // The rule modules a synthesised build program imports, from
+    // `BuildConfig::ruleModules`. When this package has no `build.mcpp` and
+    // this list is not empty, mcpp writes the program these entries describe.
+    // The program is the one the project would have written by hand, which is
+    // what makes the declaration a LAYER above `build.mcpp` rather than a
+    // second way of doing the same thing.
+    std::vector<std::string> ruleModules;
     // 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
@@ -730,6 +737,38 @@ bool cache_fresh(const fs::path& root, const fs::path& bdir, const CacheRecord&
     return true;
 }
 
+
+// The program a set of rule modules describes.
+//
+// It is the program a project writes by hand for the same rules, and that is
+// the whole contract: the declaration is a layer ABOVE `build.mcpp`, not a
+// second mechanism beside it, so a project that outgrows it copies this file
+// into its root and edits it. Synthesis then stops, because a project that has
+// its own program keeps it.
+//
+// The namespace comes from the module name with `.` exchanged for `::`, which
+// is the convention `mcpp.rules.<x>` already follows and the one a third-party
+// rule opts into by naming its module. Nothing here knows what any rule does.
+std::string synthesised_rule_program(const std::vector<std::string>& modules) {
+    std::string s =
+        "// Generated by mcpp from the build rules this package's dependencies\n"
+        "// declare. Do not edit. To take it over, copy this file to `build.mcpp`\n"
+        "// in the project root; mcpp synthesises nothing once a project has one.\n"
+        "import std;\n"
+        "import mcpp;\n";
+    for (auto const& m : modules) s += "import " + m + ";\n";
+    s += "\nint main() {\n    bool ok = true;\n";
+    for (auto const& m : modules) {
+        std::string ns;
+        for (char c : m) { if (c == '.') ns += "::"; else ns += c; }
+        // `&&` would stop at the first refusal, and a project with two rules
+        // wants both diagnostics rather than one and then silence.
+        s += "    ok = " + ns + "::compile() && ok;\n";
+    }
+    s += "    return ok ? 0 : 1;\n}\n";
+    return s;
+}
+
 } // namespace
 
 std::expected<void, std::string> run_build_program(
@@ -742,7 +781,34 @@ std::expected<void, std::string> run_build_program(
 
     fs::path src = root / "build.mcpp";
     std::error_code ec;
-    if (!fs::exists(src, ec)) return {};  // no build program — nothing to do
+    if (!fs::exists(src, ec)) {
+        // The layer above this file: when a dependency's rules claimed device
+        // sources in this package and the package wrote no program, mcpp writes
+        // the program those rules describe.
+        //
+        // SYNTHESISED ONLY IN THE ABSENCE. A project with its own `build.mcpp`
+        // keeps it, because the two would otherwise both submit the same
+        // actions and the second submission is one nobody asked for. That is
+        // also what makes the descent safe: copy the generated file into the
+        // project root, edit it, and synthesis stops.
+        if (env.ruleModules.empty()) return {};   // nothing to do
+        src = build_dir(root, env) / "build.mcpp";
+        fs::create_directories(src.parent_path(), ec);
+        const std::string text = synthesised_rule_program(env.ruleModules);
+        // Written only when it differs, so a package whose rule set did not
+        // change does not rebuild its build program on every configure.
+        bool same = false;
+        if (std::ifstream in(src, std::ios::binary); in) {
+            std::string prev((std::istreambuf_iterator<char>(in)),
+                             std::istreambuf_iterator<char>());
+            same = (prev == text);
+        }
+        if (!same) {
+            std::ofstream out(src, std::ios::binary | std::ios::trunc);
+            if (!out) return {};
+            out << text;
+        }
+    }
 
     fs::path bdir = build_dir(root, env);
     fs::path outDir = bdir / "out";

src/build/execute.cppm

@@ -1139,7 +1139,8 @@ fast_path_identity(const std::filesystem::path& projectRoot,
         std::string(mcpp::build::cache_mode_name(
             mcpp::build::resolve_cache_mode(*m, ""))),
         m->resources.files,
-        mcpp::extension_table_for(m->buildConfig.moduleExtensions),
+        mcpp::extension_table_for(m->buildConfig.moduleExtensions,
+                                  m->buildConfig.deviceExtensions),
         m->buildConfig.target,
         m->hooks.active(),
         normalize_features(featuresRequested),

src/build/plan.cppm

@@ -1017,7 +1017,8 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
     // needs it — every scanned unit arrives with its kind already set by the
     // scanner, using its OWN package's table.
     const auto rootExtTable =
-        mcpp::extension_table_for(manifest.buildConfig.moduleExtensions);
+        mcpp::extension_table_for(manifest.buildConfig.moduleExtensions,
+                                  manifest.buildConfig.deviceExtensions);
 
     // Artifact naming and shared-library link shape are properties of the
     // TARGET. Resolved once here from tc.targetTriple (empty = host target, in