feat(dyndep): plan-vs-ddi reconciliation — the compiler audits the planner

The .ddi (compiler's own P1689 scan under real flags) is the ground truth
of what phase 4 saw. ninja_backend now embeds the planner's per-TU
assumption on the dyndep edge (--expect-provides / --expect-imports /
--expect-none); `mcpp dyndep --single` compares and fails the edge on
divergence with both sides named. Mandatory for scan_overrides units (an
assertion needs its auditor); MCPP_VERIFY_MODGRAPH=1 at generation time
extends it to every module unit. Zero extra compiler invocations.

Verified: 3 unit tests; e2e negative — an fmt override deliberately
omitting imports={std} fails at DYNDEP with
  planned : provides [fmt] imports [<none>]
  compiler: provides [fmt] imports [std]
while the correct declaration builds green.

Design: .agents/docs/2026-07-08-scanner-backend-abstraction-design.md §3d.

Author: Sunrisepeak

src/build/ninja_backend.cppm

@@ -314,7 +314,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // P1: per-file dyndep rule. Converts one .ddi → .dd independently.
     append(std::format(
         "rule cxx_dyndep\n"
-        "  command = $mcpp dyndep --single --bmi-dir {} --bmi-ext {} --output $out $in\n"
+        "  command = $mcpp dyndep --single --bmi-dir {} --bmi-ext {} $expect --output $out $in\n"
         "  description = DYNDEP $out\n"
         "  restat = 1\n\n",
         traits.bmiDir, traits.bmiExt));
@@ -502,10 +502,42 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         // invalidates that file's .dd and its compile edge, not all edges.
         // Map ddi path → dd path for Phase 3 reference.
         std::map<std::string, std::string> ddi_to_dd;
+        // Plan-vs-ddi reconciliation (design 2026-07-08 scanner doc §3d):
+        // scan_overrides units ALWAYS carry their planned (provides, imports)
+        // on the dyndep edge — the compiler's own P1689 scan audits the
+        // author's assertion, per TU, failing the edge on divergence.
+        // MCPP_VERIFY_MODGRAPH=1 (read at generation time) extends the
+        // check to every module unit.
+        const bool verifyAll = [] {
+            const char* v = std::getenv("MCPP_VERIFY_MODGRAPH");
+            return v && std::string_view(v) == "1";
+        }();
+        std::map<std::string, std::string> ddi_expect;
+        for (auto& cu : plan.compileUnits) {
+            if (is_c_source(cu.source)) continue;
+            if (!cu.scanOverridden && !verifyAll) continue;
+            auto ddi = (cu.object.parent_path() / cu.source.filename()).string() + ".ddi";
+            std::string exp;
+            if (cu.providesModule)
+                exp += std::format("--expect-provides {}", *cu.providesModule);
+            if (!cu.imports.empty()) {
+                std::string csv;
+                for (auto& m : cu.imports) {
+                    if (!csv.empty()) csv += ",";
+                    csv += m;
+                }
+                if (!exp.empty()) exp += " ";
+                exp += std::format("--expect-imports {}", csv);
+            }
+            if (exp.empty()) exp = "--expect-none";
+            ddi_expect[ddi] = std::move(exp);
+        }
         for (auto& ddi : ddi_paths) {
             auto dd = ddi + ".dd";   // e.g. obj/cli.cppm.ddi.dd
             ddi_to_dd[ddi] = dd;
             append(std::format("build {} : cxx_dyndep {}\n", dd, ddi));
+            if (auto it = ddi_expect.find(ddi); it != ddi_expect.end())
+                append(std::format("  expect = {}\n", it->second));
         }
         append("\n");
 

src/build/plan.cppm

@@ -24,6 +24,9 @@ struct CompileUnit {
     std::vector<std::string>        packageCxxflags;
     std::optional<std::string>      providesModule;   // logical name, if .cppm export
     std::vector<std::string>        imports;           // logical names imported
+    // Unit came from a scan_overrides declaration — plan-vs-ddi
+    // verification is mandatory for it (ninja_backend emits --expect-*).
+    bool                            scanOverridden = false;
 };
 
 struct LinkUnit {
@@ -420,6 +423,7 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
             cu.providesModule = u.provides->logicalName;
         }
         for (auto& req : u.requires_) cu.imports.push_back(req.logicalName);
+        cu.scanOverridden = u.scanOverridden;
         plan.compileUnits.push_back(std::move(cu));
     }
 

src/cli.cppm

@@ -469,6 +469,12 @@ int run(int argc, char** argv) {
                 .help("BMI cache directory name (default: gcm.cache)"))
             .option(cl::Option("bmi-ext").takes_value().value_name("EXT")
                 .help("BMI file extension (default: .gcm)"))
+            .option(cl::Option("expect-provides").takes_value().value_name("NAME")
+                .help("(verification) planned provided module for this TU"))
+            .option(cl::Option("expect-imports").takes_value().value_name("CSV")
+                .help("(verification) planned imports for this TU, comma-separated"))
+            .option(cl::Option("expect-none")
+                .help("(verification) planner assumed no provides/imports"))
             .action(wrap_rc(cmd_dyndep)))
     ;
 

src/cli/cmd_build.cppm

@@ -182,6 +182,35 @@ export int cmd_dyndep(const mcpplibs::cmdline::ParsedArgs& parsed) {
             std::println(stderr, "error: --single requires exactly one .ddi input");
             return 2;
         }
+        // Plan-vs-ddi reconciliation: when the generator declared what the
+        // planner assumed for this TU, compare against the compiler's own
+        // scan and fail the edge on divergence (mandatory for
+        // scan_overrides units; opt-in elsewhere via MCPP_VERIFY_MODGRAPH).
+        std::string expProvides = parsed.option_or_empty("expect-provides").value();
+        std::string expImports  = parsed.option_or_empty("expect-imports").value();
+        if (!expProvides.empty() || !expImports.empty() ||
+            parsed.is_flag_set("expect-none")) {
+            std::ifstream is{std::filesystem::path{parsed.positional(0)}};
+            std::string ddiBody{std::istreambuf_iterator<char>(is), {}};
+            auto unit = mcpp::dyndep::parse_ddi(ddiBody);
+            if (!unit) {
+                std::println(stderr, "error: {}: {}", parsed.positional(0), unit.error());
+                return 1;
+            }
+            std::optional<std::string> ep;
+            if (!expProvides.empty()) ep = expProvides;
+            std::vector<std::string> ei;
+            for (std::size_t b = 0; b < expImports.size();) {
+                auto e = expImports.find(',', b);
+                if (e == std::string::npos) e = expImports.size();
+                if (e > b) ei.emplace_back(expImports.substr(b, e - b));
+                b = e + 1;
+            }
+            if (auto err = mcpp::dyndep::verify_unit_expectations(*unit, ep, ei)) {
+                std::println(stderr, "error: {}", *err);
+                return 1;
+            }
+        }
         body = mcpp::dyndep::emit_dyndep_single(parsed.positional(0), opts);
     } else {
         std::vector<std::filesystem::path> ddis;

src/dyndep.cppm

@@ -66,6 +66,18 @@ std::expected<std::string, std::string>
 emit_dyndep_single(const std::filesystem::path& ddiPath,
                    const DyndepOptions& opts = {});
 
+// Plan-vs-ddi reconciliation: compare the compiler's OWN scan of a TU
+// (the .ddi — ground truth of what phase 4 saw under real flags) against
+// the planner's assumption. Returns an error message on divergence.
+// Mandatory for scan_overrides units (an assertion needs its auditor);
+// opt-in for the rest via MCPP_VERIFY_MODGRAPH=1 (ninja_backend decides
+// at generation time). Design: .agents/docs/2026-07-08-scanner-backend-
+// abstraction-design.md §3d.
+std::optional<std::string>
+verify_unit_expectations(const UnitInfo& actual,
+                         const std::optional<std::string>& expectProvides,
+                         const std::vector<std::string>&   expectImports);
+
 } // namespace mcpp::dyndep
 
 namespace mcpp::dyndep {
@@ -327,4 +339,34 @@ emit_dyndep_single(const std::filesystem::path& ddiPath,
     return out;
 }
 
+
+std::optional<std::string>
+verify_unit_expectations(const UnitInfo& actual,
+                         const std::optional<std::string>& expectProvides,
+                         const std::vector<std::string>&   expectImports)
+{
+    std::set<std::string> act_p(actual.provides.begin(), actual.provides.end());
+    std::set<std::string> exp_p;
+    if (expectProvides && !expectProvides->empty()) exp_p.insert(*expectProvides);
+    std::set<std::string> act_r(actual.requires_.begin(), actual.requires_.end());
+    std::set<std::string> exp_r(expectImports.begin(), expectImports.end());
+
+    if (act_p == exp_p && act_r == exp_r) return std::nullopt;
+
+    auto join = [](const std::set<std::string>& s) {
+        std::string out;
+        for (auto& v : s) { if (!out.empty()) out += ", "; out += v; }
+        return out.empty() ? std::string("<none>") : out;
+    };
+    return std::format(
+        "module-graph divergence in {}:\n"
+        "  planned : provides [{}] imports [{}]\n"
+        "  compiler: provides [{}] imports [{}]\n"
+        "  The compiler's P1689 scan disagrees with the planner's assumption\n"
+        "  (stale scan_overrides declaration, or a conditional/include-carried\n"
+        "  import). Fix the declaration or the source.",
+        actual.primaryOutput.string(),
+        join(exp_p), join(exp_r), join(act_p), join(act_r));
+}
+
 } // namespace mcpp::dyndep

tests/unit/test_dyndep.cpp

@@ -104,3 +104,33 @@ TEST(Dyndep, EmitDyndepFromFiles) {
 
     std::filesystem::remove_all(tmp);
 }
+
+// ── plan-vs-ddi reconciliation (scan_overrides auditor) ──
+
+TEST(VerifyUnitExpectations, MatchPasses) {
+    mcpp::dyndep::UnitInfo u;
+    u.primaryOutput = "obj/fmt.o";
+    u.provides = {"fmt"};
+    u.requires_ = {"std"};
+    auto err = mcpp::dyndep::verify_unit_expectations(u, "fmt", {"std"});
+    EXPECT_FALSE(err.has_value()) << *err;
+}
+
+TEST(VerifyUnitExpectations, DivergenceReportsBothSides) {
+    mcpp::dyndep::UnitInfo u;
+    u.primaryOutput = "obj/fmt.o";
+    u.provides = {"fmt"};
+    u.requires_ = {"std"};
+    auto err = mcpp::dyndep::verify_unit_expectations(u, "fmt", {});
+    ASSERT_TRUE(err.has_value());
+    EXPECT_NE(err->find("divergence"), std::string::npos);
+    EXPECT_NE(err->find("planned"), std::string::npos);
+    EXPECT_NE(err->find("std"), std::string::npos);
+}
+
+TEST(VerifyUnitExpectations, ExpectNoneMatchesEmptyUnit) {
+    mcpp::dyndep::UnitInfo u;
+    u.primaryOutput = "obj/plain.o";
+    auto err = mcpp::dyndep::verify_unit_expectations(u, std::nullopt, {});
+    EXPECT_FALSE(err.has_value());
+}