mcpp.graph keeps each site's order: the module graph's stack order (link order, and so Mach-O initializer order) and the host-module depth-first orders; groups sharing one build directory build one after the other; status lines written whole

Author: speak-agent

.agents/docs/2026-09-29-workspace-build-graph-design.md

@@ -522,6 +522,7 @@ left open, the answer is recorded here.
 | The lock | `<workspace>/mcpp.lock`. A plan of all members writes the whole record; a plan of some keeps the other entries, and `--locked` then reports no entry of another member as drift. A selected member's git dependencies are locked as a root's. | prepare/records.cpp |
 | Tests | `mcpp test` keeps one plan per member (`-p X` each), in the shared directory; the members' dev-dependencies are their own. | cmd_build.cppm |
 | Concurrency | Groups are planned in turn and built on threads with a static share of the jobs; the `.build_cache` write is one locked step. | cmd_build.cppm |
+| The orders of `mcpp.graph` | Three: the stable order, the module graph's own (Kahn with the ready units on a stack, over the edges in their recorded order) and a depth-first post-order from roots in the given order. Each migrated site keeps the order it had: the module graph's unit order is the order of the objects on a link line, which Mach-O uses as initializer order, and the first migration to the stable order made openkal's `same-source` example crash at start on aarch64-macos from all three build hosts (CI, run 36486818199). With the orders restored, the link line of that example is byte-identical to 2026.9.28.3's. | modules/graph |
 | Module names across members | A graph has one module namespace (BMIs are found by name), so two members that each provide a module of one name are refused in one `--workspace` plan, as two `artifacts` programs are (#732, which tracks per-provider BMI names). Measured over the package index's 172 members: no module name is provided twice. | scanner |
 
 Readings with the implementation (Linux, llvm 22.1.8):

modules/graph/src/graph.cppm

@@ -22,6 +22,23 @@
 // a package's `[dependencies]`), so no call site has to invert its data to
 // call in.
 //
+// THREE ORDERS, AND WHY A CALLER KEEPS THE ONE IT HAD
+//
+// An order among nodes that do not constrain each other is still observable
+// when the order becomes a link order: Mach-O runs initializers in link order,
+// and the module graph's unit order is the order of the objects on the link
+// line. Changing it changed a program's initialization (measured 2026-09-29:
+// openkal's `same-source` example, linked for aarch64-macos, crashed at start
+// when its units moved to the stable order below). A caller whose order
+// reaches an artifact therefore keeps its order, and this module offers each
+// order the engine uses:
+//
+//   topological_order        Kahn, lowest ready index first (stable)
+//   stack_topological_order  Kahn, most recently readied first, over edges in
+//                            the order given (the module graph's unit order)
+//   depth_first_order        dependencies first, depth first, from roots in
+//                            the order given (the host-module orders)
+//
 // STABILITY
 //
 // `topological_order` and `levels` are Kahn's algorithm with the ready set
@@ -89,6 +106,27 @@ std::vector<std::size_t>
 closure(const AdjacencyList& deps, std::span<const std::size_t> roots,
         bool include_roots = false);
 
+// Kahn's algorithm with the ready nodes on a stack: the node readied most
+// recently is emitted next. `edges` holds (dependent, dependency) pairs over
+// nodes 0..n-1, in the order that decides the ties. This is the order of the
+// module graph's units, and so of the objects on a link line (see the header).
+std::expected<std::vector<std::size_t>, CycleError>
+stack_topological_order(std::size_t n,
+                        std::span<const std::pair<std::size_t, std::size_t>> edges);
+
+// What a dependency on a node still on the depth-first path means.
+enum class Cycles {
+    Error,   // a cycle: the order is refused with the ring
+    Skip,    // the edge is ignored; the node is emitted where it stands
+};
+
+// Dependencies first, depth first: from each root in the order given, a node
+// is emitted after every node it depends on, its dependencies visited in the
+// order of `deps[u]`. Only nodes reachable from `roots` are emitted.
+std::expected<std::vector<std::size_t>, CycleError>
+depth_first_order(const AdjacencyList& deps, std::span<const std::size_t> roots,
+                  Cycles cycles = Cycles::Error);
+
 } // namespace mcpp::graph
 
 namespace mcpp::graph {
@@ -185,6 +223,74 @@ topological_order(const AdjacencyList& deps) {
     return kahn_order(deps);
 }
 
+std::expected<std::vector<std::size_t>, CycleError>
+stack_topological_order(std::size_t n,
+                        std::span<const std::pair<std::size_t, std::size_t>> edges) {
+    std::vector<std::size_t> remaining(n, 0);
+    std::vector<std::vector<std::size_t>> dependents(n);
+    for (auto [dependent, dependency] : edges) {
+        remaining[dependent]++;
+        dependents[dependency].push_back(dependent);
+    }
+    std::vector<std::size_t> order;
+    order.reserve(n);
+    std::vector<std::size_t> ready;
+    for (std::size_t u = 0; u < n; ++u)
+        if (remaining[u] == 0) ready.push_back(u);
+    while (!ready.empty()) {
+        const std::size_t u = ready.back();
+        ready.pop_back();
+        order.push_back(u);
+        for (auto w : dependents[u])
+            if (--remaining[w] == 0) ready.push_back(w);
+    }
+    if (order.size() == n) return order;
+    // The ring, found the way `topological_order` finds one.
+    AdjacencyList deps(n);
+    for (auto [dependent, dependency] : edges) deps[dependent].push_back(dependency);
+    auto ring = kahn_order(deps);
+    if (!ring) return std::unexpected(ring.error());
+    return std::unexpected(CycleError{});
+}
+
+std::expected<std::vector<std::size_t>, CycleError>
+depth_first_order(const AdjacencyList& deps, std::span<const std::size_t> roots,
+                  Cycles cycles) {
+    const std::size_t n = deps.size();
+    std::vector<char> state(n, 0);   // 0 unseen, 1 on the current path, 2 done
+    std::vector<std::size_t> order;
+    std::vector<std::size_t> path;
+    for (auto root : roots) {
+        if (root >= n || state[root] != 0) continue;
+        std::vector<std::pair<std::size_t, std::size_t>> frame{{root, 0}};
+        state[root] = 1;
+        path.push_back(root);
+        while (!frame.empty()) {
+            auto& [u, k] = frame.back();
+            if (k < deps[u].size()) {
+                const auto v = deps[u][k++];
+                if (v >= n || state[v] == 2) continue;
+                if (state[v] == 1) {
+                    if (cycles == Cycles::Skip) continue;
+                    CycleError err;
+                    err.cycle.assign(std::ranges::find(path, v), path.end());
+                    err.cycle.push_back(v);
+                    return std::unexpected(std::move(err));
+                }
+                state[v] = 1;
+                path.push_back(v);
+                frame.push_back({v, 0});
+                continue;
+            }
+            state[u] = 2;
+            order.push_back(u);
+            path.pop_back();
+            frame.pop_back();
+        }
+    }
+    return order;
+}
+
 std::expected<std::vector<std::size_t>, CycleError>
 levels(const AdjacencyList& deps) {
     auto order = kahn_order(deps);

modules/graph/tests/test_graph.cpp

@@ -243,3 +243,90 @@ TEST(Closure, RootWithNoEdgesHasAnEmptyClosure) {
     auto c = g::closure(deps, std::array{std::size_t{0}});
     EXPECT_TRUE(c.empty());
 }
+
+// ── stack_topological_order: the module graph's unit order ──────────────────
+//
+// The order the module graph has always had, which is the order of the
+// objects on a link line. The reference below is the hand-written loop it
+// replaced, run on the same edges.
+namespace {
+std::vector<std::size_t> reference_stack_order(
+        std::size_t n, const std::vector<std::pair<std::size_t, std::size_t>>& edges) {
+    std::vector<std::size_t> indeg(n, 0);
+    std::vector<std::vector<std::size_t>> adj(n);
+    for (auto [c, p] : edges) { indeg[c]++; adj[p].push_back(c); }
+    std::vector<std::size_t> order, queue;
+    for (std::size_t i = 0; i < n; ++i) if (indeg[i] == 0) queue.push_back(i);
+    while (!queue.empty()) {
+        auto u = queue.back(); queue.pop_back();
+        order.push_back(u);
+        for (auto v : adj[u]) if (--indeg[v] == 0) queue.push_back(v);
+    }
+    return order;
+}
+}  // namespace
+
+TEST(StackTopologicalOrder, IsTheModuleGraphsHistoricalOrder) {
+    const std::vector<std::pair<std::size_t, std::size_t>> edges = {
+        {3, 0}, {4, 0}, {4, 1}, {5, 3}, {5, 4}, {6, 2}, {7, 6}, {7, 5}, {1, 2},
+    };
+    auto order = g::stack_topological_order(8, edges);
+    ASSERT_TRUE(order.has_value());
+    EXPECT_EQ(*order, reference_stack_order(8, edges));
+    // It is not the stable order: ties go to the most recently readied node.
+    g::AdjacencyList deps(8);
+    for (auto [c, p] : edges) deps[c].push_back(p);
+    EXPECT_NE(*order, *g::topological_order(deps));
+}
+
+TEST(StackTopologicalOrder, ACycleIsReportedAsItsPath) {
+    const std::vector<std::pair<std::size_t, std::size_t>> edges = {{0, 1}, {1, 2}, {2, 0}};
+    auto order = g::stack_topological_order(3, edges);
+    ASSERT_FALSE(order.has_value());
+    auto const& ring = order.error().cycle;
+    ASSERT_GE(ring.size(), 2u);
+    EXPECT_EQ(ring.front(), ring.back());
+}
+
+// ── depth_first_order: the host-module orders ───────────────────────────────
+
+TEST(DepthFirstOrder, DependenciesFirstFromEachRootInOrder) {
+    // 0 -> {2, 1}, 1 -> {3}, 2 -> {3}: from root 0, dependency 2 is visited
+    // before 1 because that is the order `deps[0]` lists them in.
+    g::AdjacencyList deps(4);
+    deps[0] = {2, 1};
+    deps[1] = {3};
+    deps[2] = {3};
+    auto order = g::depth_first_order(deps, std::array{std::size_t{0}});
+    ASSERT_TRUE(order.has_value());
+    EXPECT_EQ(*order, (std::vector<std::size_t>{3, 2, 1, 0}));
+}
+
+TEST(DepthFirstOrder, OnlyWhatTheRootsReachIsEmitted) {
+    g::AdjacencyList deps(4);
+    deps[1] = {0};
+    deps[3] = {2};
+    auto order = g::depth_first_order(deps, std::array{std::size_t{1}});
+    ASSERT_TRUE(order.has_value());
+    EXPECT_EQ(*order, (std::vector<std::size_t>{0, 1}));
+}
+
+TEST(DepthFirstOrder, ACycleIsAnErrorNamingTheRing) {
+    g::AdjacencyList deps(3);
+    deps[0] = {1};
+    deps[1] = {2};
+    deps[2] = {1};
+    auto order = g::depth_first_order(deps, std::array{std::size_t{0}});
+    ASSERT_FALSE(order.has_value());
+    EXPECT_EQ(order.error().cycle, (std::vector<std::size_t>{1, 2, 1}));
+}
+
+TEST(DepthFirstOrder, ACycleCanBeSkipped) {
+    g::AdjacencyList deps(2);
+    deps[0] = {1};
+    deps[1] = {0};
+    auto order = g::depth_first_order(deps, std::array{std::size_t{0}, std::size_t{1}},
+                                      g::Cycles::Skip);
+    ASSERT_TRUE(order.has_value());
+    EXPECT_EQ(*order, (std::vector<std::size_t>{1, 0}));
+}

src/build/prepare/features.cpp

@@ -1019,28 +1019,25 @@ static std::vector<prov::HostModule> host_module_units(const PrepareState& st, s
         byName.emplace(pending[i].name, i);
 
     // deps[u] = the pending-list indices `u` imports BY NAME within this
-    // same package. mcpp.graph's stable tie-break (lowest index first among
-    // unconstrained nodes) is what preserves path order in the
-    // unconstrained case; the old hand-written DFS achieved the same thing
-    // by always trying the path-sorted list from the front.
+    // same package, in import order. A depth-first order from every unit in
+    // path order emits the first unit that can be emitted, which is what
+    // preserves path order in the unconstrained case, and is the order the
+    // build program's objects are linked in.
     mcpp::graph::AdjacencyList deps(pending.size());
     for (std::size_t u = 0; u < pending.size(); ++u)
         for (auto const& want : pending[u].imports)
             if (auto it = byName.find(want); it != byName.end())
                 deps[u].push_back(it->second);
+    std::vector<std::size_t> roots(pending.size());
+    std::iota(roots.begin(), roots.end(), std::size_t{0});
 
     // A CYCLE IS LEFT TO THE COMPILER, ON PURPOSE. It is ill-formed C++ and
     // the compiler says so with the two units named; refusing here would
     // report the same fact in a worse place, and getting the ordering wrong
-    // is no longer possible either way -- so on a cycle this falls back to
-    // declaration order instead of surfacing mcpp.graph's CycleError.
+    // is no longer possible either way -- so the edge that closes a cycle is
+    // skipped.
     std::vector<std::size_t> order;
-    if (auto ordered = mcpp::graph::topological_order(deps)) {
-        order = std::move(*ordered);
-    } else {
-        order.resize(pending.size());
-        std::iota(order.begin(), order.end(), std::size_t{0});
-    }
+    order = *mcpp::graph::depth_first_order(deps, roots, mcpp::graph::Cycles::Skip);
 
     for (auto i : order) push(pending[i].path, std::move(pending[i].name));
     return out;
@@ -1163,39 +1160,24 @@ step6_host_module_registration(PrepareState& state) {
                     }
                 }
 
-                // Dependency-first order, so a rule's own host modules are
-                // compiled BEFORE it. That ordering is the entire mechanism:
-                // the compile loop in build_program.cppm accumulates the
-                // module flags as it goes, so each entry sees the BMIs of
-                // everything ahead of it, and "a rule may import another
-                // rule" needs no second machinery — only this sort.
-                //
-                // Restricted to `c`'s own reachable closure (not the whole
-                // project) and reindexed to a dense local graph before
-                // calling mcpp.graph: a cycle elsewhere among packages `c`
-                // never reaches must not fail `c`'s build.
-                auto reach = mcpp::graph::closure(pkgHostDeps, direct,
-                                                   /*include_roots=*/true);
-                std::map<std::size_t, std::size_t> local;
-                for (std::size_t i = 0; i < reach.size(); ++i)
-                    local.emplace(reach[i], i);
-                mcpp::graph::AdjacencyList sub(reach.size());
-                for (std::size_t i = 0; i < reach.size(); ++i)
-                    for (auto q : pkgHostDeps[reach[i]])
-                        if (auto it = local.find(q); it != local.end())
-                            sub[i].push_back(it->second);
-
-                auto topo = mcpp::graph::topological_order(sub);
+                // Post-order DFS, so a rule's own host modules are compiled
+                // BEFORE it. That ordering is the entire mechanism: the
+                // compile loop in build_program.cppm accumulates the module
+                // flags as it goes, so each entry sees the BMIs of everything
+                // ahead of it, and "a rule may import another rule" needs no
+                // second machinery — only this sort. It walks only what `c`
+                // reaches, so a cycle elsewhere never fails `c`'s build.
+                auto topo = mcpp::graph::depth_first_order(pkgHostDeps, direct);
                 if (!topo) {
                     // A cycle, reported AS a cycle and naming the packages
                     // on it. A depth limit would answer a different
                     // question and would answer it later.
                     std::string ring;
                     bool first = true;
-                    for (auto li : topo.error().cycle) {
+                    for (auto q : topo.error().cycle) {
                         if (!first) ring += " -> ";
                         first = false;
-                        ring += identity(reach[li]);
+                        ring += identity(q);
                     }
                     return std::unexpected(std::format(
                         "build rules form an import cycle: {}\n"
@@ -1205,18 +1187,18 @@ step6_host_module_registration(PrepareState& state) {
                 }
 
                 std::vector<prov::HostModule> ordered;
-                for (auto li : *topo) {
-                    auto p = reach[li];
+                for (auto p : *topo) {
                     for (auto& hm : units(p)) {
                         hm.importable = isDirect.contains(p);
                         ordered.push_back(std::move(hm));
                     }
                 }
 
                 // Every provider on this consumer's rule closure, transitive
-                // ones included -- `reach` is exactly that set, and a rule
-                // imported by another rule declares payloads just as directly.
-                state.hostModuleProvidersByConsumer[c].assign(reach.begin(), reach.end());
+                // ones included, and a rule imported by another rule declares
+                // payloads just as directly.
+                std::set<std::size_t> reached(topo->begin(), topo->end());
+                state.hostModuleProvidersByConsumer[c].assign(reached.begin(), reached.end());
 
                 if (auto clash = prov::host_module_collision(ordered))
                     return std::unexpected(*clash);

src/build/stage.cppm

@@ -173,7 +173,9 @@ bool links_on_placement(const std::filesystem::path& p) {
 // it and the link can be made, and a copy otherwise (another volume, FAT or
 // exFAT, a permission), so the fallback is today's behaviour.
 // Returns an empty error_code on success; otherwise the most informative error
-// (the in-place one — that's where 1224 / 32 shows up).
+// (the in-place one — that's where 1224 / 32 shows up), or the rename's when
+// the destination shares its bytes with another name and is not written in
+// place.
 std::error_code write_once(const std::filesystem::path& src,
                            const std::filesystem::path& dst) {
     auto tmp = temp_sibling(dst);

src/cli/cmd_build.cppm

@@ -328,19 +328,28 @@ export int cmd_build(const mcpplibs::cmdline::ParsedArgs& parsed) {
             return r != 0 ? r : rc;
         }
         const std::size_t hw = std::max(1u, std::thread::hardware_concurrency());
+        std::set<std::filesystem::path> directories;
+        for (auto const& c : contexts) directories.insert(c.outputDir.lexically_normal());
         for (auto& c : contexts) {
             const std::size_t want = c.plan.scheduleNinjaJobs > 0
                 ? static_cast<std::size_t>(c.plan.scheduleNinjaJobs) : hw + 2;
             c.plan.scheduleNinjaJobs = static_cast<int>(
-                std::max<std::size_t>(1, want / contexts.size()));
+                std::max<std::size_t>(1, want / directories.size()));
         }
+        // Concurrency is across build directories. Two groups whose values
+        // resolve to one directory (one toolchain spelled two ways) are built
+        // one after the other in it, since one ninja owns a directory.
+        std::map<std::filesystem::path, std::vector<std::size_t>> byDirectory;
+        for (std::size_t i = 0; i < contexts.size(); ++i)
+            byDirectory[contexts[i].outputDir.lexically_normal()].push_back(i);
         std::vector<int> results(contexts.size(), 0);
         {
             std::vector<std::jthread> builds;
-            for (std::size_t i = 0; i < contexts.size(); ++i)
-                builds.emplace_back([&, i] {
-                    results[i] = run_build_with_hooks(contexts[i], verbose, no_cache,
-                                                      ov.target_triple);
+            for (auto const& [dir, indices] : byDirectory)
+                builds.emplace_back([&, indices] {
+                    for (auto i : indices)
+                        results[i] = run_build_with_hooks(contexts[i], verbose, no_cache,
+                                                          ov.target_triple);
                 });
         }
         for (int r : results)