fix(plan, symbol_provision): a build program's objects stay in this package's images, and vague linkage is not a second provider

Two defects that serving the SYCL runtime's OpenCL adapter made active. Both
were latent, neither is caused by #596, and both were found by the checks this
branch sharpened rather than by reading.

A BUILD PROGRAM'S OBJECTS REACHED A DEPENDENCY'S IMAGE. `role = "object"` with
no named target attaches to "every linked image", and that read as "every link
unit in this plan" -- which includes the shared library a dependency
contributes. Measured: `compat:opencl`'s ICD loader, a C library, came out of
the link carrying `saxpy_device` and thirty-seven `sycl::` instantiations, 193
dynamic symbols where its own API is 154, and the process held two copies of
the device island. `LinkUnit::dependencyOwned` now separates the images this
package produces from the ones a dependency contributes. After: 0 sycl symbols,
154 exports, all of them its own `cl*` entry points.

Latent until a SYCL project first had a shared dependency, which is what
declaring `compat:opencl` did.

VAGUE LINKAGE IS NOT A SECOND PROVIDER. `DynamicSymbol` recorded the symbol's
TYPE and not its BINDING, so template instantiations, inline functions and
vtables -- which the C++ ABI emits into every image and expects the loader to
unify -- were counted as a second provider. `hide_static_cxx_runtime` had
already written that rule in a comment; nothing enforced it one layer up. The
binding is recorded now, weak definitions are counted rather than reported, and
the count is printed for the reason every denominator in this area is printed.

Both were invisible while the same artifact still had 68 real findings on top
of them.

One test moved from positional to designated initialisation: adding a field to
`Conflict` bound the provider list to a bool -- a string literal converts to
one, so it compiled and the list silently became empty.

Author: speak-agent

.agents/docs/2026-09-09-dlopen-surface-and-two-unwinders.md

@@ -616,6 +616,36 @@ predates it, the example's README announces it, and the example runs correctly
 across it every time nothing throws. #596 is simply the first time something
 threw.
 
+## 8.5 What serving the OpenCL adapter uncovered
+
+R7's reversal put a shared library into every SYCL project's plan for the first
+time, and two latent defects became active the moment it did. Both are repaired
+here; neither is caused by #596, and neither would have been found by reading.
+
+**A build program's objects reached a dependency's image.** `role = "object"`
+with no named target attaches to "every linked image", and that was reading as
+"every link unit in this plan" -- which includes the shared library a
+dependency contributes. Measured: `compat:opencl`'s ICD loader, a C library,
+came out of the link with `saxpy_device` and thirty-seven `sycl::`
+instantiations in it, 193 dynamic symbols where its own API is 154, and the
+process held two copies of the island. `LinkUnit::dependencyOwned` now says
+which images are this package's, and the rule reads "every image THIS PACKAGE
+produces".
+
+**The symbol-provision check could not tell a weak definition from a strong
+one.** `DynamicSymbol` recorded the type and not the binding, so vague-linkage
+definitions -- template instantiations, inline functions, vtables, which the
+C++ ABI emits into every image and expects the loader to unify -- were counted
+as a second provider. `hide_static_cxx_runtime`'s own comment had already
+written the rule ("must not ... unifying those across the process is the
+intended C++ ABI behaviour"); nothing enforced it one layer up. The binding is
+recorded now, weak definitions are counted rather than reported, and the count
+is printed so "clean" cannot read as "did not look".
+
+Both were invisible before because the same artifact had 68 real findings
+sitting on top of them. A check whose noise is repaired shows what the noise
+was covering, which is the third time this issue has produced that shape.
+
 ## 9. What this touches, across the three repositories
 
 The review that asks the other question: not "is each repair right" but "what

CHANGELOG.md

@@ -56,6 +56,26 @@ libgcc_s 本来就在进程里(libstdc++ 需要它),所以这一步只点名一
 `12 24 36 48`。**顺带推翻了示例里一条写下来的结论** —— 设备镜像不匹配的那次抛出
 并非拦不住,它拦不住只是因为 unwinder 是坏的。
 
+### 构建程序的对象不再进入依赖的映像
+
+`role = "object"` 的 action 在没有点名 target 时按「每一个链接映像」附着,而这句
+一直被读成「计划里的每一个链接单元」—— 其中包含**依赖贡献的共享库**。实测:
+`compat:opencl` 的 ICD loader(一个纯 C 库)链完带着 `saxpy_device` 和 37 个
+`sycl::` 实例化,导出 193 个符号而它自己的 API 只有 154 个,进程里于是有两份岛。
+`LinkUnit::dependencyOwned` 现在区分「本包产出的映像」与「依赖贡献的映像」。
+
+这条一直潜伏着:直到 SYCL 工程第一次有了共享依赖才被激活。
+
+### 重复符号检查按符号绑定分流
+
+`DynamicSymbol` 只记了类型不记绑定,于是 vague-linkage 定义(模板实例、inline
+函数、vtable —— C++ ABI 要求每个映像各发一份、由加载器统一)被算成了第二个提供者。
+`hide_static_cxx_runtime` 的注释早就写下了这条规则,但上一层没有任何东西执行它。
+现在绑定被记录,weak 定义只计数不算冲突,而且**计数会被打印** —— 否则「干净」读起来
+就等于「没看」。
+
+同样是被那 68 条真冲突盖住的:修好噪声之后才看得见噪声盖住了什么。
+
 ### 重复符号警告会说出 unwinder 的真实后果
 
 该警告此前把后果一律描述为「库自己的那份副本不会被调用」。对 `_Unwind_*` 这一族,

src/build/plan.cppm

@@ -80,6 +80,19 @@ struct CompileUnit {
 struct LinkUnit {
     std::string                     targetName;
     enum Kind { Binary, StaticLibrary, SharedLibrary, TestBinary } kind = Binary;
+    // Does this image belong to a DEPENDENCY rather than to the package being
+    // built? A `kind = "shared"` dependency contributes a link unit to the
+    // consumer's plan, and that unit is not one of the consumer's targets.
+    //
+    // It decides where a `role = "object"` action's outputs go. "Every linked
+    // image" is the right default for a build program's objects -- a test
+    // binary and a static library both need them -- but it was reading as
+    // "every link unit in the plan", so a device island was linked into a
+    // dependency's shared library as well. Measured: `compat:opencl`'s ICD
+    // loader, a C library, came out carrying `saxpy_device` and thirty-seven
+    // `sycl::` instantiations, and the process then had two copies of the
+    // island. Latent until a SYCL project first had a shared dependency.
+    bool                            dependencyOwned = false;
     // Normally relative to plan.outputDir. A `role = "object"` action's outputs
     // land here ABSOLUTE, on purpose: ninja identifies a file by the string an
     // edge declares, and the action edge declares whatever prepare_actions
@@ -1676,6 +1689,7 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
         LinkUnit lu;
         lu.targetName = dep.target.name;
         lu.kind       = LinkUnit::SharedLibrary;
+        lu.dependencyOwned = true;
         lu.output     = dep.output;
         lu.importLibrary = import_library_for(dep.target, naming);
         if (msvcTarget && !lu.importLibrary.empty())

src/build/prepare.cppm

@@ -10358,10 +10358,21 @@ prepare_build(bool print_fingerprint,
                 // consumes `lu.objects`, so the objects an action produced
                 // belong there for exactly the reason a compiled `.cpp`'s do:
                 // the target's content is what it was told to contain.
-                const bool image = lu.kind == mcpp::build::LinkUnit::Binary
+                //
+                // AND NOT A DEPENDENCY'S IMAGE. "Every linked image" means
+                // every image THIS PACKAGE produces; a `kind = "shared"`
+                // dependency contributes a link unit to this plan and is not
+                // one of them. Without the qualifier the SYCL example's device
+                // island was linked into `compat:opencl`'s ICD loader as well
+                // -- a C library carrying `saxpy_device` -- and the process
+                // held two copies of it. An action that means to reach a
+                // dependency's target cannot: it is not this package's to
+                // fill, and naming it explicitly already fails as unknown.
+                const bool image = !lu.dependencyOwned
+                               && (lu.kind == mcpp::build::LinkUnit::Binary
                                 || lu.kind == mcpp::build::LinkUnit::SharedLibrary
                                 || lu.kind == mcpp::build::LinkUnit::StaticLibrary
-                                || lu.kind == mcpp::build::LinkUnit::TestBinary;
+                                || lu.kind == mcpp::build::LinkUnit::TestBinary);
                 const bool wanted = a.targets.empty()
                     ? image
                     : std::find(a.targets.begin(), a.targets.end(),

src/build/runtime_validation.cppm

@@ -1036,7 +1036,21 @@ check_symbol_provision(const mcpp::build::BuildPlan& plan,
                 .defines = names,
             });
         }
-        report.conflicts = sp::conflicting_exports(*exported, providers);
+        // WEAK DEFINITIONS ARE COUNTED, NOT REPORTED.
+        //
+        // A template instantiation or an inline function is emitted into every
+        // image that needs it and the loader keeps one; that is the C++ ABI
+        // working. Reporting it names a correct build. Measured on the SYCL
+        // example once the real findings were repaired: thirty-nine shared
+        // symbols remained and thirty-seven were `sycl::queue` and
+        // `sycl::buffer` instantiations from the same headers libsycl was
+        // built from -- and the other two were the island's own `extern "C"`
+        // entry points, which libsycl does not define at all.
+        auto all = sp::conflicting_exports(*exported, providers);
+        for (auto const& conflict : all)
+            if (conflict.isWeak) ++report.sharedWeak;
+        std::erase_if(all, [](auto const& c) { return c.isWeak; });
+        report.conflicts = std::move(all);
         report.status = report.conflicts.empty() ? sp::Status::Clean
                                                  : sp::Status::Conflict;
         findings.push_back({artifact, std::move(report)});

src/build/symbol_provision.cppm

@@ -55,6 +55,11 @@ export namespace mcpp::build::symbol_provision {
 struct Export {
     std::string name;
     bool        isFunc = false;
+    // A vague-linkage definition (STB_WEAK): a template instantiation, an
+    // inline function, a vtable. Every translation unit that needs one emits
+    // it and the loader unifies them; that is the C++ ABI working, not an
+    // image displacing a library's own copy.
+    bool        isWeak = false;
 };
 
 // One object that could also supply a symbol, as the report will name it.
@@ -67,6 +72,7 @@ struct Provider {
 struct Conflict {
     std::string              name;
     bool                     isFunc = false;
+    bool                     isWeak = false;
     std::vector<std::string> alsoProvidedBy;
 };
 
@@ -92,6 +98,14 @@ struct Report {
     std::size_t           exported = 0;
     std::size_t           total = 0;
     std::vector<Conflict> conflicts;
+    // Shared vague-linkage definitions, counted and not listed.
+    //
+    // They are NOT a finding: the C++ ABI emits a template instantiation into
+    // every image that needs it and expects the loader to keep one. Counting
+    // them is still worth doing -- a reader who runs `nm -D` sees them and has
+    // to be told which ones this check decided about, or "clean" reads as
+    // "did not look".
+    std::size_t           sharedWeak = 0;
     // Why, for the two non-answers. Empty for Clean and Conflict.
     std::string           reason;
 
@@ -169,7 +183,8 @@ exported_definitions(const mcpp::platform::elf::DynamicSymbols& symbols) {
         // share an address with relocated data from being excused.
         if (!symbol.isFunc && symbols.copyRelocations.contains(symbol.value))
             continue;
-        out.push_back(Export{ .name = symbol.name, .isFunc = symbol.isFunc });
+        out.push_back(Export{ .name = symbol.name, .isFunc = symbol.isFunc,
+                              .isWeak = symbol.isWeak });
     }
     std::ranges::sort(out, {}, &Export::name);
     return out;
@@ -179,7 +194,8 @@ std::vector<Conflict> conflicting_exports(std::span<const Export> exports,
                                           std::span<const Provider> closure) {
     std::vector<Conflict> out;
     for (auto const& exported : exports) {
-        Conflict conflict{ .name = exported.name, .isFunc = exported.isFunc };
+        Conflict conflict{ .name = exported.name, .isFunc = exported.isFunc,
+                           .isWeak = exported.isWeak };
         for (auto const& provider : closure) {
             if (std::ranges::find(provider.defines, exported.name)
                 != provider.defines.end())
@@ -223,6 +239,13 @@ std::string Report::explain(std::string_view artifact) const {
 
     body += "  Also provided by:\n";
     for (auto const& label : providers) body += std::format("    {}\n", label);
+    if (sharedWeak > 0)
+        body += std::format(
+            "  ({} vague-linkage definition{} -- template instantiations, inline\n"
+            "  functions, vtables -- {} also shared and are NOT part of this\n"
+            "  finding: the C++ ABI emits one per image and the loader keeps one.)\n",
+            sharedWeak, sharedWeak == 1 ? "" : "s",
+            sharedWeak == 1 ? "is" : "are");
 
     // WHY it matters, then what to do — IN THE ORDER THAT ACTUALLY WORKS.
     //

src/runtime/elf.cppm

@@ -137,6 +137,13 @@ struct DynamicSymbol {
     // dynamic symbol table therefore has exactly one cause — the linker
     // exported it so that some shared object's reference would bind to it.
     bool          isFunc = false;
+    // STB_WEAK. A vague-linkage definition -- a template instantiation, an
+    // inline function, a vtable -- which the C++ ABI emits into every
+    // translation unit that needs it and expects the loader to unify across
+    // the process. That is the intended behaviour, not a leak, so a caller
+    // asking "is this image providing something twice" has to be able to tell
+    // it from a strong definition that displaces a library's own.
+    bool          isWeak = false;
     std::uint64_t value = 0;   // st_value; the key a copy relocation matches
 };
 
@@ -274,6 +281,7 @@ constexpr std::uint64_t kDtGnuHash = 0x6ffffef5;
 constexpr std::uint64_t kSymEntrySize  = 24;
 constexpr std::uint64_t kRelaEntrySize = 24;
 
+constexpr unsigned char kStbWeak     = 2;
 constexpr unsigned char kSttObject   = 1;
 constexpr unsigned char kSttFunc     = 2;
 constexpr unsigned char kSttGnuIfunc = 10;
@@ -731,6 +739,7 @@ inspect_dynamic_symbols(const std::filesystem::path& object) {
         out.defined.push_back(DynamicSymbol{
             .name   = std::move(*name),
             .isFunc = (type == detail::kSttFunc || type == detail::kSttGnuIfunc),
+            .isWeak = (bind == detail::kStbWeak),
             .value  = *value,
         });
     }

tests/unit/test_symbol_provision.cpp

@@ -137,8 +137,14 @@ TEST(SymbolProvision, TheReportNamesEveryProviderAndCapsTheSymbolList) {
     report.status = sp::Status::Conflict;
     report.total = 217;
     for (int i = 0; i < 20; ++i)
+        // DESIGNATED, not positional. A field added to `Conflict` between
+        // `isFunc` and `alsoProvidedBy` bound the provider list to a bool
+        // here -- a string literal converts to one, so it compiled, and the
+        // provider list silently became empty.
         report.conflicts.push_back(sp::Conflict{
-            std::format("sym{}", i), true, {"/pkg/lib/libz.so.1"}});
+            .name = std::format("sym{}", i),
+            .isFunc = true,
+            .alsoProvidedBy = {"/pkg/lib/libz.so.1"}});
     report.exported = report.conflicts.size();
 
     auto text = report.explain("consumer");
@@ -199,3 +205,48 @@ TEST(SymbolProvision, OrdinaryLinkFlagsDoNotVoidThePredicate) {
         "-O2", "-Wl,-rpath,$ORIGIN", "-lz", "-Wl,--as-needed",
         "-Wl,--enable-new-dtags", "-static-libstdc++", "-shared"}));
 }
+
+// ── vague linkage is not a second provider ─────────────────────────────────
+//
+// A template instantiation, an inline function or a vtable is emitted into
+// every image that needs it and the loader keeps one. That is the C++ ABI
+// working, and reporting it names a correct build.
+//
+// Measured on the SYCL example once the real findings were repaired: of the
+// thirty-nine symbols the image still shared with `libsycl.so.9`,
+// thirty-seven were `sycl::queue` and `sycl::buffer` instantiations from the
+// same headers libsycl was built from -- and the remaining two were the
+// island's own `extern "C"` entry points, which libsycl does not define. A
+// check that could not tell binding from name reported all of them.
+
+TEST(SymbolProvision, AWeakDefinitionIsCarriedThroughAsWeak) {
+    auto s = image();
+    auto weak = func("_ZN4sycl3_V15queueD2Ev");
+    weak.isWeak = true;
+    s.defined.push_back(weak);
+    s.defined.push_back(func("saxpy_device"));
+    auto exports = sp::exported_definitions(s);
+    ASSERT_TRUE(exports.has_value());
+    ASSERT_EQ(exports->size(), 2u);
+    // Sorted by name: the mangled one first.
+    EXPECT_TRUE((*exports)[0].isWeak);
+    EXPECT_FALSE((*exports)[1].isWeak);
+}
+
+TEST(SymbolProvision, AConflictRemembersWhetherItsDefinitionIsWeak) {
+    std::vector<sp::Export> exports{
+        { .name = "_ZN4sycl3_V15queueD2Ev", .isFunc = true, .isWeak = true },
+        { .name = "inflate",                .isFunc = true, .isWeak = false },
+    };
+    std::vector<sp::Provider> closure{
+        { .label = "libsycl.so.9",
+          .defines = {"_ZN4sycl3_V15queueD2Ev", "inflate"} },
+    };
+    auto conflicts = sp::conflicting_exports(exports, closure);
+    ASSERT_EQ(conflicts.size(), 2u);
+    // Both are shared; only the binding separates them, and the caller is what
+    // decides which one is a finding. Asserted here rather than in the caller
+    // so the DATA carries the distinction even if a future caller forgets it.
+    EXPECT_TRUE(conflicts[0].isWeak);
+    EXPECT_FALSE(conflicts[1].isWeak);
+}