feat(scanner): scan_overrides — author-asserted scan results bypass the text scan

For sha256-pinned third-party module units whose imports sit behind
preprocessor guards (fmt's official src/fmt.cc: #ifdef FMT_IMPORT_STD
import std;), the import set is a CONSTANT — recomputing it per build with
compiler processes is the wrong cost placement, and the M1 text scan must
reject it. Instead the descriptor asserts the scan result as data:

    scan_overrides = {
        ["*/src/fmt.cc"] = { provides = { "fmt" }, imports = { "std" } },
    }

Matched files skip scan_file(); the declared unit enters the graph with
scanOverridden=true (the flag plan-vs-ddi verification keys on). Both
surfaces parse it: xpkg mcpp segment and mcpp.toml [scan_overrides."glob"].
Every glob must match >=1 collected source (unmatched = loud error).
A unit may declare at most one provided module.

Verified: 3 unit tests (xpkg parse, empty-declaration reject, toml parse);
full suite green; end-to-end: mcpp-index fmtlib.fmt rewritten WITHOUT its
3.4KB generated_files copy — upstream fmt.cc verbatim + -DFMT_IMPORT_STD +
override — builds and its member test passes (import fmt; works).

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

Author: Sunrisepeak

src/manifest/toml.cppm

@@ -191,6 +191,42 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             if (cval.is_string()) m.capabilityPins[cap] = cval.as_string();
     }
 
+    // [scan_overrides."<glob>"] — author-asserted scan results (see
+    // manifest:types ScanOverride). provides/imports are string arrays.
+    if (auto* so_table = doc->get_table("scan_overrides");
+        so_table && !so_table->empty()) {
+        for (auto& [glob, val] : *so_table) {
+            if (!val.is_table()) {
+                return std::unexpected(error(origin,
+                    std::format("[scan_overrides.\"{}\"] must be a table", glob)));
+            }
+            manifest::ScanOverride ov;
+            auto& st = val.as_table();
+            auto read_names = [&](const char* key, std::vector<std::string>& out)
+                -> std::optional<std::string> {
+                auto it = st.find(key);
+                if (it == st.end()) return std::nullopt;
+                if (!it->second.is_array())
+                    return std::format("scan_overrides.\"{}\".{} must be an array", glob, key);
+                for (auto& v : it->second.as_array()) {
+                    if (!v.is_string() || v.as_string().empty())
+                        return std::format("scan_overrides.\"{}\".{} entries must be non-empty strings", glob, key);
+                    out.push_back(v.as_string());
+                }
+                return std::nullopt;
+            };
+            if (auto msg = read_names("provides", ov.provides))
+                return std::unexpected(error(origin, *msg));
+            if (auto msg = read_names("imports", ov.imports))
+                return std::unexpected(error(origin, *msg));
+            if (ov.provides.empty() && ov.imports.empty()) {
+                return std::unexpected(error(origin, std::format(
+                    "scan_overrides.\"{}\" declares neither provides nor imports", glob)));
+            }
+            m.modules.scanOverrides.emplace(glob, std::move(ov));
+        }
+    }
+
     auto* targets_table = doc->get_table("targets");
     if (targets_table && !targets_table->empty()) {
     for (auto& [tname, tval] : *targets_table) {

src/manifest/types.cppm

@@ -49,10 +49,23 @@ struct Language {
     bool                        importStd = true;
 };
 
+// Author-asserted scan result for one source glob (scan_overrides).
+// Files matched by the glob bypass the M1 text scan entirely; the declared
+// (provides, imports) enter the module graph directly. Sound because the
+// declaration is verified against the compiler's own P1689 (.ddi) output
+// at build time — assertion + verification instead of computation.
+// Design: .agents/docs/2026-07-08-scanner-backend-abstraction-design.md §3-pre.
+struct ScanOverride {
+    std::vector<std::string> provides;   // module logical names the file exports
+    std::vector<std::string> imports;    // module logical names the file imports
+};
+
 struct Modules {
     std::vector<std::string>    sources;        // glob patterns
     std::vector<std::string>    exports_;       // declared module names (optional)
     bool                        strict = false;
+    // glob → declared scan result; every glob must match ≥1 source file.
+    std::map<std::string, ScanOverride> scanOverrides;
 };
 
 struct Target {

src/manifest/xpkg.cppm

@@ -1123,6 +1123,65 @@ synthesize_from_xpkg_lua(std::string_view luaContent,
                 rc.skip_ws_and_comments();
             }
         }
+        else if (key == "scan_overrides") {
+            // `{ ["glob"] = { provides = { "m" }, imports = { "std" } }, ... }`
+            // Author-asserted scan results (manifest:types ScanOverride):
+            // matched files bypass the M1 text scan; verified against the
+            // compiler's P1689 output at build time.
+            if (!cur.consume('{')) {
+                return std::unexpected(ManifestError{
+                    "expected '{' after `scan_overrides =`", m.sourcePath, 0, 0});
+            }
+            cur.skip_ws_and_comments();
+            while (!cur.eof() && cur.peek() != '}') {
+                auto glob = cur.read_key();
+                if (glob.empty()) break;
+                cur.skip_ws_and_comments();
+                if (!cur.consume('=') || !cur.consume('{')) {
+                    return std::unexpected(ManifestError{
+                        std::format("malformed scan_overrides entry '{}'", glob),
+                        m.sourcePath, 0, 0});
+                }
+                ScanOverride ov;
+                cur.skip_ws_and_comments();
+                while (!cur.eof() && cur.peek() != '}') {
+                    auto sub = cur.read_key();
+                    cur.skip_ws_and_comments();
+                    if (sub.empty() || !cur.consume('=')) break;
+                    cur.skip_ws_and_comments();
+                    std::vector<std::string>* arr =
+                        sub == "provides" ? &ov.provides
+                      : sub == "imports"  ? &ov.imports
+                      : nullptr;
+                    if (arr && cur.peek() == '{') {
+                        cur.consume('{');
+                        cur.skip_ws_and_comments();
+                        while (!cur.eof() && cur.peek() != '}') {
+                            auto s = cur.read_string();
+                            if (!s.empty()) arr->push_back(std::move(s));
+                            cur.skip_ws_and_comments();
+                        }
+                        cur.consume('}');
+                    } else {
+                        return std::unexpected(ManifestError{
+                            std::format("scan_overrides '{}': unknown subfield '{}' "
+                                        "(expected provides / imports)", glob, sub),
+                            m.sourcePath, 0, 0});
+                    }
+                    cur.skip_ws_and_comments();
+                }
+                cur.consume('}');
+                if (ov.provides.empty() && ov.imports.empty()) {
+                    return std::unexpected(ManifestError{
+                        std::format("scan_overrides '{}' declares neither provides "
+                                    "nor imports", glob),
+                        m.sourcePath, 0, 0});
+                }
+                m.modules.scanOverrides.emplace(std::move(glob), std::move(ov));
+                cur.skip_ws_and_comments();
+            }
+            cur.consume('}');
+        }
         else if (key == "schema") {
             // Descriptor schema tag (e.g. "0.1") — accepted, currently
             // informational only.

src/modgraph/graph.cppm

@@ -22,6 +22,9 @@ struct SourceUnit {
     std::vector<ModuleId>           requires_;
     bool                            isModuleInterface = false;   // .cppm with export module
     bool                            isImplementation   = false;   // .cpp without export
+    // Unit built from a manifest scan_overrides declaration instead of a
+    // real scan — plan-vs-ddi verification is mandatory for these.
+    bool                            scanOverridden     = false;
 };
 
 struct Graph {

src/modgraph/scanner.cppm

@@ -439,7 +439,45 @@ void scan_one_into(ScanResult& result,
         manifest.package.namespace_.empty()
             ? manifest.package.name
             : manifest.package.namespace_ + "." + manifest.package.name;
+    // scan_overrides: author-asserted units bypass the text scan entirely.
+    // Every override glob must match at least one collected source file —
+    // an unmatched glob is a typo or a stale declaration, not a no-op.
+    std::map<std::string, int> overrideHits;
+    for (auto const& [glob, ov] : manifest.modules.scanOverrides)
+        overrideHits[glob] = 0;
+
     for (auto const& f : all_files) {
+        const mcpp::manifest::ScanOverride* ov = nullptr;
+        for (auto const& [glob, o] : manifest.modules.scanOverrides) {
+            if (path_matches_glob(f, root, glob)) {
+                ov = &o;
+                ++overrideHits[glob];
+                break;
+            }
+        }
+        if (ov) {
+            SourceUnit u;
+            u.path           = f;
+            u.packageName    = qualifiedName;
+            u.scanOverridden = true;
+            if (!ov->provides.empty()) {
+                u.provides          = ModuleId{ov->provides.front()};
+                u.isModuleInterface = true;
+                if (ov->provides.size() > 1) {
+                    result.errors.push_back(ScanError{f, 0,
+                        "scan_overrides: a unit may declare at most one "
+                        "provided module"});
+                    continue;
+                }
+            }
+            for (auto const& name : ov->imports)
+                u.requires_.push_back(ModuleId{name});
+            u.localIncludeDirs = localIncludeDirs;
+            u.packageCflags    = packageCflags;
+            u.packageCxxflags  = packageCxxflags;
+            result.graph.units.push_back(std::move(u));
+            continue;
+        }
         auto r = scan_file(f, qualifiedName);
         if (!r) {
             result.errors.push_back(r.error());
@@ -450,6 +488,14 @@ void scan_one_into(ScanResult& result,
         r->packageCxxflags = packageCxxflags;
         result.graph.units.push_back(std::move(*r));
     }
+
+    for (auto const& [glob, hits] : overrideHits) {
+        if (hits == 0) {
+            result.errors.push_back(ScanError{root, 0, std::format(
+                "scan_overrides glob '{}' matched no source file "
+                "(typo, or the glob is not covered by `sources`)", glob)});
+        }
+    }
 }
 
 // Phase 2: producerOf + edges over already-collected units.

tests/unit/test_manifest.cpp

@@ -1440,3 +1440,77 @@ package = {
     EXPECT_EQ(m->xpkgUnknownKeys[0], "bogus_key");
     EXPECT_EQ(m->xpkgUnknownKeys[1], "future_table");
 }
+
+// ── scan_overrides: author-asserted scan results ──
+// Design: .agents/docs/2026-07-08-scanner-backend-abstraction-design.md §3-pre
+
+TEST(ScanOverrides, XpkgSegmentParses) {
+    constexpr auto lua = R"(
+package = {
+    spec = "1",
+    namespace = "fmtlib",
+    name = "fmtlib.fmt",
+    xpm  = { linux = { ["12.2.0"] = { url = "u", sha256 = "h" } } },
+    mcpp = {
+        sources  = { "*/src/fmt.cc" },
+        cxxflags = { "-DFMT_IMPORT_STD" },
+        scan_overrides = {
+            ["*/src/fmt.cc"] = { provides = { "fmt" }, imports = { "std" } },
+        },
+        targets  = { ["fmt"] = { kind = "lib" } },
+    },
+}
+)";
+    auto m = mcpp::manifest::synthesize_from_xpkg_lua(lua, "fmtlib.fmt", "12.2.0");
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    ASSERT_EQ(m->modules.scanOverrides.size(), 1u);
+    auto& ov = m->modules.scanOverrides.at("*/src/fmt.cc");
+    ASSERT_EQ(ov.provides.size(), 1u);
+    EXPECT_EQ(ov.provides[0], "fmt");
+    ASSERT_EQ(ov.imports.size(), 1u);
+    EXPECT_EQ(ov.imports[0], "std");
+    EXPECT_TRUE(m->xpkgUnknownKeys.empty());
+}
+
+TEST(ScanOverrides, XpkgRejectsEmptyDeclaration) {
+    constexpr auto lua = R"(
+package = {
+    spec = "1",
+    name = "so",
+    xpm  = { linux = { ["1.0.0"] = { url = "u", sha256 = "h" } } },
+    mcpp = {
+        sources = { "a.cc" },
+        scan_overrides = { ["a.cc"] = { } },
+        targets = { ["so"] = { kind = "lib" } },
+    },
+}
+)";
+    auto m = mcpp::manifest::synthesize_from_xpkg_lua(lua, "so", "1.0.0");
+    ASSERT_FALSE(m.has_value());
+    EXPECT_NE(m.error().message.find("neither provides nor imports"),
+              std::string::npos) << m.error().format();
+}
+
+TEST(ScanOverrides, TomlParses) {
+    constexpr auto src = R"(
+[package]
+name = "app"
+version = "0.1.0"
+[language]
+standard = "c++23"
+[modules]
+sources = ["src/**/*.cppm", "vendor/fmt.cc"]
+["scan_overrides"."vendor/fmt.cc"]
+provides = ["fmt"]
+imports  = ["std"]
+[targets.app]
+kind = "bin"
+main = "src/main.cpp"
+)";
+    auto m = mcpp::manifest::parse_string(src);
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    ASSERT_EQ(m->modules.scanOverrides.size(), 1u);
+    auto& ov = m->modules.scanOverrides.at("vendor/fmt.cc");
+    EXPECT_EQ(ov.provides, std::vector<std::string>{"fmt"});
+    EXPECT_EQ(ov.imports,  std::vector<std::string>{"std"});
+}