Workspace build graph: member targets gated by features, the workspace package reads its own workspace dependencies, pooled flags kept for units no member owns, the group link line checked for hermeticity, runtime files placed in the product directory

Author: speak-agent

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

@@ -497,3 +497,35 @@ version. The other repositories change only where the release requires it.
 | T13 | the release canaries (xlings, mcppls), both rooted workspaces, and the plugins' CI | xlings, mcppls, mcpp-plugins | T11 |
 | T14 | sandbox verification with the CN mirror; issues commented and closed | all | T12, T13 |
 | T15 | acceptance on the validation project's pull request: its Windows CI against 1828 s, the core library compiled once, the Release layout | the validation project | T14 |
+
+## 17. Implementation record (2026-09-29)
+
+Implemented in one change on `feat/workspace-build-graph`, released as
+2026.9.29.1. Where the implementation settled a question the sections above
+left open, the answer is recorded here.
+
+| Question | Answer | Where |
+|---|---|---|
+| The root of a rooted workspace | Every workspace plan has a virtual root; the workspace's own package is the member `"."`, whose products keep `bin/`. A command at the root selects it alone. The package is then the same node in every selection. | `select_workspace_members` (prepare/manifest.cpp) |
+| Which values separate plans | Every root-position value (`root_position_key`): the toolchain and target rows, the standard, the graph-wide `[build]` keys, the profiles, the indices, the capability and tool pins. The virtual root copies them from the group's first member, so a group and its root cannot disagree. | `mcpp.project` |
+| A member's build program | Runs after every dependency's program, where a root's runs, with its own artifacts directory and a graph document of its closure in which it is `root`. A workspace member reached as another member's dependency runs there too, so its program sees one environment in every selection. | `step9_member_build_programs` (prepare/target_side.cpp) |
+| A member's identity | A path member that declares no namespace keeps its bare name (a root's identity) instead of the default namespace a path dependency receives. | prepare/graph.cpp |
+| Per-member link data | Each package's normalised link flags are read when the plan is made; a member's link group holds the plan's flags followed by its closure's, and its closure's runtime contract, and `compute_flags` renders it from a copy of the plan with the group swapped in. The link edge carries the group's `ldflags` and `c_ldflags`. | `make_plan` step 6, `swap_link_group`, ninja_backend.cppm |
+| Graph-built shared libraries | Linked once at `bin/`, placed in each product directory whose units load them. | `LinkGroup::placements` |
+| Linked placement | Shared libraries only; other deployed files are copied, since a program may write a file beside itself and a link would carry the write to its source. A linked destination is never written in place. | mcpp.build.stage |
+| `-p X` and `--workspace` in one directory | `build.ninja` records a request tag (the plan's members and the requested features), and every fast path compares it; one `.build_cache` entry per selection and configuration group. Alternating selections re-plan (one plan of the selection) and recompile nothing. | graph_shape.cppm, execute.cppm |
+| 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 |
+
+Readings with the implementation (Linux, llvm 22.1.8):
+
+| Reading | 2026.9.28.3 | 2026.9.29.1 |
+|---|---|---|
+| chain of five libraries and a program, `--workspace`, nothing built | 36.8 s | 0.51 s |
+| the same, nothing changed | not replayed | 3 ms |
+| `-p app`, nothing changed | not replayed | 3 ms |
+
+mcpp's own repository, a rooted workspace, builds itself with the new engine
+(full build, gcc 16.1.0, 115 s), and its module tests run through member plans
+(`mcpp test -p graph`, `-p versioning`).

cdb.json

@@ -1668,7 +1668,7 @@ CompileFlags compute_flags(const BuildPlan& plan) {
             // same build re-runs edges for no reason.
             std::ranges::sort(sources);
             for (auto const& src : sources)
-                in.candidates.push_back({{src}, std::filesystem::path("bin") / src.filename(),
+                in.candidates.push_back({{src}, plan.productDir / src.filename(),
                                          rp::Kind::Toolchain});
         }
         auto decision = rp::resolve(in);

src/build/flags.cppm

@@ -3923,6 +3923,22 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
                                       flags.graphLinkIsolated, plan.packageRoots); !h) {
         return std::unexpected(BuildError{h.error(), {}});
     }
+    // A workspace member's units link with their group's line (§15), which
+    // is checked the same way.
+    if (!plan.linkGroups.empty()) {
+        BuildPlan view = plan;
+        std::set<std::string> checked{flags.ld};
+        for (auto& g : view.linkGroups) {
+            swap_link_group(view, g);
+            const auto gf = compute_flags(view);
+            swap_link_group(view, g);
+            if (!checked.insert(gf.ld).second) continue;
+            if (auto h = verify_hermetic_link(plan.toolchain, gf.ld, plan.outputDir,
+                                              plan.manifest.buildConfig.allowHostLibs,
+                                              gf.graphLinkIsolated, plan.packageRoots); !h)
+                return std::unexpected(BuildError{h.error(), {}});
+        }
+    }
     stage("hermetic-check");
 
     // When the toolchain comes from mcpp's private sandbox, use the

src/build/ninja_backend.cppm

@@ -493,6 +493,10 @@ struct BuildPlan {
     // musl-gcc 15.1 modules failed to emit vector<pair<string,string>>'s
     // move-ctor instantiation across the module boundary (release link error).
     std::vector<RuntimeCapabilityProvider> runtimeProviders;
+    // Where the files the runtime needs are placed beside the programs,
+    // relative to outputDir: `bin`, or a workspace member's product directory
+    // while its link group is swapped in (§15).
+    std::filesystem::path              productDir = "bin";
 
     // A workspace plan's per-member link data (workspace design 2026-09-29
     // §15). A selected member's link units link the member's closure -- the
@@ -540,6 +544,7 @@ void swap_link_group(BuildPlan& plan, BuildPlan::LinkGroup& g) {
     std::swap(plan.runtimeDlopenLibs, g.runtimeDlopenLibs);
     std::swap(plan.runtimeCapabilities, g.runtimeCapabilities);
     std::swap(plan.runtimeProviders, g.runtimeProviders);
+    std::swap(plan.productDir, g.productDir);
 }
 
 // Merge the generic facts exported by the already-selected xlings
@@ -2834,12 +2839,14 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
         for (auto i : closureIdx) closure.insert(qualified_package_name(packages[i].manifest));
 
         // The member's link group: the closure's link flags after the
-        // plan's own, in the order a root build gives them (the member, then
-        // its dependencies in discovery order), and the closure's runtime.
+        // root's own (`packages[0]` is snapshotted before any dependency is
+        // loaded, so it holds the profile's flags and nothing pooled), in the
+        // order a root build gives them (the member, then its dependencies in
+        // discovery order), and the closure's runtime.
         BuildPlan::LinkGroup group;
         group.member = owner;
         group.productDir = productDir;
-        group.ldflags = manifest.buildConfig.ldflags;
+        group.ldflags = packages[0].linkUsage.ldflags;
         for (auto i : closureIdx)
             for (auto const& f : packages[i].linkUsage.ldflags)
                 group.ldflags.push_back(f);

src/build/plan.cppm

@@ -323,9 +323,12 @@ static std::expected<void, std::string> step6_activate_features(PrepareState& st
             // place costs nothing. What the gate exists for is the shape where
             // a target's mere presence changes how the package is linked into
             // every consumer — and that is exactly a `shared` or `lib` target.
+            // A selected workspace member builds every target, so every one
+            // of its targets is gated, as a root's are (§15).
             std::erase_if(pkg.manifest.targets,
                           [&](const mcpp::manifest::Target& t) {
-                if (t.kind != mcpp::manifest::Target::Library
+                if (!pkg.memberProducts
+                    && t.kind != mcpp::manifest::Target::Library
                     && t.kind != mcpp::manifest::Target::SharedLibrary)
                     return false;
                 for (auto const& rf : t.requiredFeatures)
@@ -2040,11 +2043,8 @@ static std::expected<void, std::string> step6_dependency_build_programs(PrepareS
             // A CLAIM THAT ONLY EVER TIGHTENS.
             if (bcDep.runExclusive && !exclusiveBefore)
                 state.m->buildConfig.runExclusive = true;
-            // A workspace plan reads each package's own flags when it links
-            // a member's closure; nothing is pooled in its root (§15).
-            if (!state.workspacePlan())
-                state.m->buildConfig.ldflags.insert(state.m->buildConfig.ldflags.end(),
-                    bcDep.ldflags.begin() + ldN, bcDep.ldflags.end());
+            state.m->buildConfig.ldflags.insert(state.m->buildConfig.ldflags.end(),
+                bcDep.ldflags.begin() + ldN, bcDep.ldflags.end());
         }
 
         // apply() may have added interface defines to packages' publicUsage

src/build/prepare/features.cpp

@@ -377,13 +377,13 @@ static std::vector<std::string> propagateLinkFlags(
         // flags with the same reading its own flags receive, and an element
         // that packs several tokens is several words on both sides.
         //
-        // A workspace plan links each member's closure with that closure's own
-        // flags (workspace design 2026-09-29 §15), read from each package when
-        // the plan is made, so nothing is pooled in the virtual root.
+        // In a workspace plan the pooled list serves the units no member owns
+        // (a dependency's shared library); a member's units link with its own
+        // closure's flags, which the plan reads from each package (§15).
         std::vector<std::string> added;
         for (auto const& word : mcpp::manifest::flag_words(depManifest.buildConfig.ldflags)) {
             auto normalized = mcpp::manifest::flag_element(normalizeDepLdflag(depRoot, word));
-            if (!state.workspacePlan()) state.m->buildConfig.ldflags.push_back(normalized);
+            state.m->buildConfig.ldflags.push_back(normalized);
             added.push_back(std::move(normalized));
         }
         return added;
@@ -1637,7 +1637,15 @@ step4b_acquire_dependency_source(PrepareState& state, WorklistItemCtx& ctx) {
                                        const std::filesystem::path& wsRoot) {
                 return inherit_as_workspace_member(*dep_manifest, ws, wsRoot, dep_root);
             };
-            if (depIsMember) {
+            // A rooted workspace's own package, the member "." of a workspace
+            // plan (§15), is the workspace's manifest: it reads its own
+            // `[workspace.dependencies]`, as it did as the root.
+            const bool depIsWorkspacePackage = state.workspacePlan() && state.wsManifest
+                && dep_root.lexically_normal() == state.runtimeWorkspaceRoot.lexically_normal();
+            if (depIsWorkspacePackage) {
+                mcpp::project::merge_workspace_deps(*dep_manifest, *state.wsManifest,
+                                                    state.runtimeWorkspaceRoot);
+            } else if (depIsMember) {
                 if (auto bad = inheritAsMember(*state.wsManifest, state.runtimeWorkspaceRoot))
                     return std::unexpected(*bad);
             } else if (!gitMember.empty()) {