@@ -525,6 +525,35 @@ updater = { path = "../updater", artifacts = ["updater"] }
 > by nothing that made a decision: writing it produced a manifest that loaded,
 > no diagnostic, and no effect.
 
+### One module per name in each program (mcpp 2026.9.30.2+)
+
+A module name identifies one module within one program. The compilers name a
+module's entities and its initializer after the module, so a program cannot
+link two modules of one name. A build can hold several programs (a package and
+the programs it ships through `artifacts`, the members of a workspace), and
+each of them may have its own module of one name.
+
+- An import is resolved within the importing package's closure: the package
+  and every package it reaches through its dependencies. The closure does not
+  follow `artifacts`, `tools` or `[build-dependencies]` edges, whose programs
+  are built separately.
+- Two packages that one program links may not provide the same name. The build
+  is refused, and the message names the package whose closure holds both.
+- When two packages of one build provide a name, each BMI lies below its
+  package's directory in the build directory, and every compile that may import
+  the name is told which one it means: through a module map with GCC, through
+  `-fmodule-file=` with Clang, and through `/reference` with MSVC. When every
+  name has one provider, the build directory and every command are as they
+  were before.
+- A package that provides such a name is compiled in the project, not served
+  from the global dependency cache.
+- clangd finds a module by its name in the compilation database, so for a name
+  two packages provide it may show the other program's module. The build is
+  not affected.
+
+A module that several programs share is best provided by one package that the
+others depend on; it is then compiled once.
+
 ## Current limitations
 
 - **Two things need the network, and only two:** resolving a branch that has no
 
@@ -451,9 +451,11 @@ member that several members use is compiled once.
   `compile_commands.json` once, as the union of their databases (2026.9.29.5+).
 - **No-op builds.** A command repeated with nothing changed is answered by one
   check per configuration, without planning.
-- **Module names.** Members built in one graph share one module namespace:
-  two members that each provide a module of the same name cannot be built in
-  one `--workspace` command; build each with `-p`.
+- **Module names.** A module name is unique within one program, not within one
+  graph (2026.9.30.2+). Two members that share no program may each provide a
+  module of the same name, and one `--workspace` command builds both; a member
+  that links both is refused. See
+  [05 — One module per name in each program](05-dependencies.md#one-module-per-name-in-each-program-mcpp-20269302).
 
 ## 6. Directory Layout
 
 
@@ -478,6 +478,25 @@ updater = { path = "../updater", artifacts = ["updater"] }
 > 这个段很早就能被解析，而直到 2026.8.29.1，没有任何做决定的代码读过它：
 > 写下它得到的是一份能加载的 manifest、零诊断、零效果。
 
+### 每个程序里一个名字只对应一个模块（mcpp 2026.9.30.2+）
+
+模块名在一个程序之内标识一个模块。编译器以模块名命名模块的实体与初始化函数，因此一个程序
+不能链接两个同名模块。一次构建可以包含多个程序（一个包，以及它经 `artifacts` 发布的程序；
+工作区的各个成员），其中每个程序都可以有自己的同名模块。
+
+- import 在导入方所在包的闭包内解析：该包，以及它经依赖到达的每个包。闭包不沿
+  `artifacts`、`tools` 与 `[build-dependencies]` 边延伸，这些边对应的程序另行构建。
+- 被同一个程序链接的两个包不得提供同一个名字。此时构建被拒绝，消息点名其闭包同时包含两者的包。
+- 同一次构建中有两个包提供同一个名字时，各自的 BMI 位于构建目录中其所属包的子目录下，
+  每一个可能导入该名字的编译都会被告知它指哪一个：GCC 经模块映射文件，Clang 经
+  `-fmodule-file=`，MSVC 经 `/reference`。每个名字只有一个提供方时，构建目录与每条命令都与
+  以前相同。
+- 提供这种名字的包在项目内编译，不从全局依赖缓存取用。
+- clangd 在编译数据库中按名字查找模块，因此对两个包提供的同一个名字，编辑器可能显示另一个
+  程序的模块。构建不受影响。
+
+几个程序共用的模块，最好由一个包提供、其余的包依赖它；这样它只编译一次。
+
 ## 当前边界
 
 - **只有两件事需要网络，而且只有这两件：** 解析一个在 lock 里没有 commit 的
 
@@ -414,8 +414,9 @@ mcpp test --workspace --workspace-timeout 1800   # whole fan-out (default 0 = no
   多个配置的命令只写一次根目录的 `compile_commands.json`，内容为各配置数据库的并集
   （2026.9.29.5+）。
 - **无事可做的构建。** 在没有任何改动时重复执行的命令，每个配置只做一次检查，不重新规划。
-- **模块名。** 在同一张图中构建的成员共享一个模块命名空间：两个成员各自提供同名模块时，不能在
-  同一条 `--workspace` 命令中构建；分别用 `-p` 构建。
+- **模块名。** 模块名在一个程序之内唯一，而不是在一张图之内唯一（2026.9.30.2+）。不共享任何
+  程序的两个成员可以各自提供同名模块，一条 `--workspace` 命令会把两者都构建出来；同时链接两者的
+  成员会被拒绝。见 [05 —— 每个程序里一个名字只对应一个模块](05-dependencies.md#每个程序里一个名字只对应一个模块mcpp-20269302)。
 
 ## 6. 目录布局
 
 
@@ -54,8 +54,18 @@ struct DyndepOptions {
     // A unit that provides nothing (implementation unit, plain .cpp) is not
     // split, so it keeps its single record.
     bool splitModuleEdges = false;
+    // mcpp#732: module name -> BMI path, for a unit whose package's closure
+    // holds a name two packages provide (the plan's module map). A name it
+    // lists takes that path; any other takes `<bmiDir>/<name><bmiExt>`.
+    const std::map<std::string, std::string, std::less<>>* moduleMap = nullptr;
 };
 
+// The BMI path `name` takes under `opts`: the module map's, or the flat one.
+std::string bmi_path_for(std::string_view name, const DyndepOptions& opts);
+
+// Parse a module map: `<module name> <BMI path>` per line.
+std::map<std::string, std::string, std::less<>> parse_module_map(std::string_view body);
+
 // Parse a single .ddi JSON body to a UnitInfo. Returns unexpected on JSON error.
 std::expected<UnitInfo, std::string> parse_ddi(std::string_view body);
 
@@ -188,6 +198,26 @@ std::size_t find_key(std::string_view s, std::size_t start, std::string_view key
 
 } // namespace
 
+std::string bmi_path_for(std::string_view name, const DyndepOptions& opts) {
+    if (opts.moduleMap)
+        if (auto it = opts.moduleMap->find(name); it != opts.moduleMap->end()) return it->second;
+    return std::string(opts.bmiDir) + "/" + bmi_basename(name, opts.bmiExt);
+}
+
+std::map<std::string, std::string, std::less<>> parse_module_map(std::string_view body) {
+    std::map<std::string, std::string, std::less<>> out;
+    while (!body.empty()) {
+        auto nl = body.find('\n');
+        auto line = body.substr(0, nl);
+        body.remove_prefix(nl == std::string_view::npos ? body.size() : nl + 1);
+        while (!line.empty() && (line.back() == '\r' || line.back() == ' ')) line.remove_suffix(1);
+        auto sp = line.find(' ');
+        if (sp == std::string_view::npos || sp == 0) continue;
+        out.emplace(std::string(line.substr(0, sp)), std::string(line.substr(sp + 1)));
+    }
+    return out;
+}
+
 std::string bmi_basename(std::string_view logicalName,
                           std::string_view ext) {
     std::string out;
@@ -207,8 +237,7 @@ namespace {
 std::vector<std::string> dyndep_targets(const UnitInfo& u, const DyndepOptions& opts) {
     std::vector<std::string> t;
     if (opts.splitModuleEdges && !u.provides.empty()) {
-        t.push_back(std::string(opts.bmiDir) + "/"
-                    + bmi_basename(u.provides.front(), opts.bmiExt));
+        t.push_back(bmi_path_for(u.provides.front(), opts));
     }
     if (!u.primaryOutput.empty()) t.push_back(u.primaryOutput.string());
     return t;
@@ -314,8 +343,7 @@ std::string emit_dyndep(const std::vector<UnitInfo>&     units,
                 bool selfProvides = false;
                 for (auto& p : u.provides) if (p == r) { selfProvides = true; break; }
                 if (selfProvides) continue;
-                std::string bmiDir(opts.bmiDir);
-                add_implicit(bmiDir + "/" + bmi_basename(r, opts.bmiExt));
+                add_implicit(bmi_path_for(r, opts));
             }
             line += "\n  restat = 1\n";
             out += line;
@@ -367,8 +395,7 @@ emit_dyndep_single(const std::filesystem::path& ddiPath,
             for (auto& p : u->provides) if (p == r) { selfProvides = true; break; }
             if (selfProvides) continue;
             if (firstImplicit) { line += " |"; firstImplicit = false; }
-            std::string bmiDir(opts.bmiDir);
-            line += " " + bmiDir + "/" + bmi_basename(r, opts.bmiExt);
+            line += " " + bmi_path_for(r, opts);
         }
         line += "\n  restat = 1\n";
         out += line;
 
@@ -441,6 +441,10 @@ struct BmiTraits {
     std::string_view compileModulesFlag;    // " -fmodules" (GCC) | ""
     std::string_view stdBmiUsePrefix;       // "" | " -fmodule-file=std=" | " /reference std="
     std::string_view stdCompatBmiUsePrefix; // "" | " -fmodule-file=std.compat=" | " /reference std.compat="
+    // Binds one module name to one BMI file for one compile, as `<prefix><name>=<path>`
+    // (mcpp#732: two modules of one name in one build directory). "" for GCC,
+    // which binds names through a mapper file instead.
+    std::string_view moduleFileUsePrefix;   // "" | " -fmodule-file=" | " /reference "
     std::string_view moduleOutputPrefix;    // "" | " -fmodule-output=" | " /ifcOutput "
     std::string_view bmiSearchPrefix;       // "" | " -fprebuilt-module-path=" | " /ifcSearchDir "
     // How this compiler is TOLD that a translation unit is a module interface.
@@ -647,6 +651,7 @@ BmiTraits bmi_traits(const Toolchain& tc) {
             .compileModulesFlag = "",
             .stdBmiUsePrefix = " /reference std=",
             .stdCompatBmiUsePrefix = " /reference std.compat=",
+            .moduleFileUsePrefix = " /reference ",
             .moduleOutputPrefix = " /ifcOutput ",
             .bmiSearchPrefix = " /ifcSearchDir ",
             // Pre-existing behaviour, unchanged: cl has always been told
@@ -670,6 +675,7 @@ BmiTraits bmi_traits(const Toolchain& tc) {
             .compileModulesFlag = "",
             .stdBmiUsePrefix = " -fmodule-file=std=",
             .stdCompatBmiUsePrefix = " -fmodule-file=std.compat=",
+            .moduleFileUsePrefix = " -fmodule-file=",
             .moduleOutputPrefix = " -fmodule-output=",
             .bmiSearchPrefix = " -fprebuilt-module-path=",
             .moduleInterfaceLangFlag = " -x c++-module",
@@ -689,6 +695,7 @@ BmiTraits bmi_traits(const Toolchain& tc) {
         .compileModulesFlag = " -fmodules",
         .stdBmiUsePrefix = "",
         .stdCompatBmiUsePrefix = "",
+        .moduleFileUsePrefix = "",
         .moduleOutputPrefix = "",
         .bmiSearchPrefix = "",
         // GCC decides interface-ness from the content (`export module`), so
 
@@ -62,11 +62,15 @@ stage_configure_prerequisites(const BuildPlan& plan) {
         if (!unit.servedFromCache || unit.providesModule.empty()
             || unit.cachedBmi.empty()) continue;
 
-        std::string fileName;
-        fileName.reserve(unit.providesModule.size() + traits.bmiExt.size());
-        for (char ch : unit.providesModule)
-            fileName.push_back(ch == ':' ? '-' : ch);
-        fileName += traits.bmiExt;
+        // Where the plan placed the unit's BMI: below its package's directory
+        // when two packages provide its module name (mcpp#732).
+        std::string fileName = unit.bmiFile;
+        if (fileName.empty()) {
+            fileName.reserve(unit.providesModule.size() + traits.bmiExt.size());
+            for (char ch : unit.providesModule)
+                fileName.push_back(ch == ':' ? '-' : ch);
+            fileName += traits.bmiExt;
+        }
 
         auto result = stage_one(
             unit.cachedBmi, plan.outputDir / traits.bmiDir / fileName,