fix: resolve overlinking false positives for staging outputs

When a package output inherits from a staging cache, the staging
cache's host dependencies aren't installed in the prefix during
overlinking checks. This means libraries like libz.so.1 can't be
attributed to zlib, even though zlib is a run dependency via inherited
run_exports.

Fix: at staging build time, capture a LibraryNameMap (filename to
package mapping) from PrefixInfo while conda-meta still exists. Store
it in the staging cache metadata, thread it to BuildOutput, and use it
as a fallback in perform_linking_checks when resolve_libraries can't
find the library on disk.

Fixes #2186

Supersedes #2210

Author: Hofer-Julian

crates/rattler_build_core/src/build.rs

@@ -136,10 +136,12 @@ pub async fn run_build(
     // This will build or restore staging caches and return their dependencies/sources if inherited
     let staging_result = output.process_staging_caches(tool_configuration).await?;
 
-    // If we inherit from a staging cache, store its dependencies and sources
-    if let Some((deps, sources)) = staging_result {
+    // If we inherit from a staging cache, store its dependencies, sources, and
+    // library name map for overlinking checks
+    if let Some((deps, sources, library_name_map)) = staging_result {
         output.finalized_cache_dependencies = Some(deps);
         output.finalized_cache_sources = Some(sources);
+        output.staging_library_name_map = Some(library_name_map);
     }
 
     // Fetch sources for this output

crates/rattler_build_core/src/post_process/checks.rs

@@ -528,6 +528,7 @@ pub fn perform_linking_checks(
     let system_libs = find_system_libs(output)?;
 
     let prefix_info = PrefixInfo::from_prefix(output.prefix())?;
+    let staging_lib_map = output.staging_library_name_map.as_ref();
 
     let host_dso_packages = host_run_export_dso_packages(output, &prefix_info.package_to_nature);
     tracing::trace!("Host run_export DSO packages: {host_dso_packages:#?}",);
@@ -644,6 +645,26 @@ pub fn perform_linking_checks(
                 );
             }
 
+            // Fallback: if the library couldn't be resolved on disk (e.g. from
+            // a staging cache whose host deps are not installed), try to match
+            // it by filename against the cached library name map.
+            if let Some(lib_map) = staging_lib_map
+                && let Some(providing_package) = lib_map.find_package(lib)
+                && run_dependency_names.contains(&providing_package)
+            {
+                tracing::debug!(
+                    "Library {lib:?} matched to '{}' via staging library name map",
+                    providing_package.as_normalized()
+                );
+                link_info.linked_packages.push(LinkedPackage {
+                    name: lib.to_path_buf(),
+                    link_origin: LinkOrigin::ForeignPackage(
+                        providing_package.as_normalized().to_string(),
+                    ),
+                });
+                continue;
+            }
+
             // Check if the library is one of the system libraries (i.e. comes from sysroot).
             if system_libs.allow.is_match(lib) && !system_libs.deny.is_match(lib) {
                 link_info.linked_packages.push(LinkedPackage {
@@ -730,7 +751,21 @@ pub fn perform_linking_checks(
 
 #[cfg(test)]
 mod tests {
+    use std::collections::BTreeMap;
+    use std::sync::{Arc, Mutex};
+
+    use rattler_conda_types::{MatchSpec, package::CondaArchiveType};
+    use rattler_solve::{ChannelPriority, SolveStrategy};
+
     use super::*;
+    use crate::render::resolved_dependencies::{
+        DependencyInfo, FinalizedDependencies, FinalizedRunDependencies, SourceDependency,
+    };
+    use crate::system_tools::SystemTools;
+    use crate::types::{
+        BuildConfiguration, BuildSummary, Directories, PackagingSettings,
+        PlatformWithVirtualPackages,
+    };
     use fs_err;
 
     #[test]
@@ -1088,4 +1123,136 @@ mod tests {
         assert!(result.is_err());
         assert!(result.unwrap_err().to_string().contains("Failed to parse"));
     }
+
+    /// Creates a minimal `Output` for testing `perform_linking_checks`.
+    ///
+    /// The recipe is parsed from YAML. The remaining fields (`BuildConfiguration`,
+    /// `FinalizedDependencies`, etc.) are not part of the recipe format and must
+    /// be constructed manually.
+    fn create_test_output(
+        target_platform: Platform,
+        host_prefix: PathBuf,
+        build_prefix: PathBuf,
+        run_deps: Vec<&str>,
+        recipe_yaml: &str,
+    ) -> crate::metadata::Output {
+        let recipe: rattler_build_recipe::Stage1Recipe =
+            serde_yaml::from_str(recipe_yaml).expect("failed to parse recipe YAML");
+
+        let pvp = PlatformWithVirtualPackages {
+            platform: target_platform,
+            virtual_packages: vec![],
+        };
+
+        let depends = run_deps
+            .into_iter()
+            .map(|name| {
+                DependencyInfo::Source(SourceDependency {
+                    spec: MatchSpec::from_str(name, rattler_conda_types::ParseStrictness::Lenient)
+                        .unwrap(),
+                })
+            })
+            .collect();
+
+        crate::metadata::Output {
+            recipe,
+            build_configuration: BuildConfiguration {
+                target_platform,
+                host_platform: pvp.clone(),
+                build_platform: pvp,
+                variant: BTreeMap::new(),
+                hash: rattler_build_recipe::stage1::HashInfo {
+                    hash: "test".into(),
+                    prefix: String::new(),
+                },
+                directories: Directories {
+                    host_prefix,
+                    build_prefix,
+                    ..Default::default()
+                },
+                channels: vec![],
+                channel_priority: ChannelPriority::Strict,
+                solve_strategy: SolveStrategy::Highest,
+                timestamp: chrono::Utc::now(),
+                subpackages: BTreeMap::new(),
+                packaging_settings: PackagingSettings {
+                    archive_type: CondaArchiveType::Conda,
+                    compression_level: 1,
+                },
+                store_recipe: false,
+                force_colors: false,
+                sandbox_config: None,
+                exclude_newer: None,
+            },
+            finalized_dependencies: Some(FinalizedDependencies {
+                build: None,
+                host: None,
+                run: FinalizedRunDependencies {
+                    depends,
+                    constraints: vec![],
+                    run_exports: Default::default(),
+                },
+            }),
+            finalized_sources: None,
+            finalized_cache_dependencies: None,
+            finalized_cache_sources: None,
+            staging_library_name_map: None,
+            build_summary: Arc::new(Mutex::new(BuildSummary::default())),
+            system_tools: SystemTools::new("test", "0.0.0"),
+            extra_meta: None,
+        }
+    }
+
+    /// Simulates a staging output scenario: the binary (zlink) links against
+    /// libz.so.1, zlib IS in the run dependencies (via inherited run_exports),
+    /// but zlib is NOT installed in the host prefix (no conda-meta, no library
+    /// files). With the staging library name map providing the fallback
+    /// mapping, the overlinking check should pass.
+    #[test]
+    fn test_staging_overlinking() {
+        let test_data = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../test-data/binary_files");
+
+        let tmp = tempfile::tempdir().unwrap();
+        let tmp_prefix = tmp.path().join("tmp_prefix");
+        let host_prefix = tmp.path().join("host_prefix");
+        let build_prefix = tmp.path().join("build_prefix");
+        fs_err::create_dir_all(&tmp_prefix).unwrap();
+        fs_err::create_dir_all(&host_prefix).unwrap();
+        fs_err::create_dir_all(&build_prefix).unwrap();
+
+        let binary_dest = tmp_prefix.join("zlink");
+        fs_err::copy(test_data.join("zlink"), &binary_dest).unwrap();
+
+        let mut output = create_test_output(
+            Platform::Linux64,
+            host_prefix,
+            build_prefix,
+            vec!["zlib"],
+            r#"
+            package:
+              name: test-pkg
+              version: "1.0.0"
+            build:
+              dynamic_linking:
+                overlinking_behavior: error
+                missing_dso_allowlist:
+                  - "libc*"
+            "#,
+        );
+        output.staging_library_name_map =
+            Some(crate::post_process::package_nature::LibraryNameMap {
+                library_to_package: [("libz.so.1".to_string(), "zlib".to_string())]
+                    .into_iter()
+                    .collect(),
+            });
+
+        let new_files: HashSet<PathBuf> = [binary_dest].into_iter().collect();
+
+        let result = perform_linking_checks(&output, &new_files, &tmp_prefix);
+        assert!(
+            result.is_ok(),
+            "Expected overlinking check to pass since zlib is a run dependency \
+             with a staging library name map, but got: {result:?}"
+        );
+    }
 }

crates/rattler_build_core/src/post_process/package_nature.rs

@@ -215,6 +215,74 @@ impl PrefixInfo {
     }
 }
 
+/// A mapping from shared library filenames to the package that provides them.
+///
+/// This is used as a fallback during overlinking checks when the staging
+/// cache's host dependencies are not physically installed in the prefix.
+/// Instead of requiring files on disk, this allows name-based attribution
+/// of libraries to packages.
+#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
+pub struct LibraryNameMap {
+    /// Maps library filenames (e.g. "libz.so.1", "libz.1.dylib") to the
+    /// package name that provides them.
+    pub library_to_package: HashMap<String, String>,
+}
+
+impl LibraryNameMap {
+    /// Build a `LibraryNameMap` from a `PrefixInfo` by extracting the
+    /// filenames of all files that look like shared objects.
+    pub(crate) fn from_prefix_info(prefix_info: &PrefixInfo) -> Self {
+        let mut library_to_package = HashMap::new();
+
+        for (path, package_name) in &prefix_info.path_to_package {
+            if is_dso(&path.path)
+                && let Some(file_name) = path.path.file_name()
+            {
+                library_to_package.insert(
+                    file_name.to_string_lossy().to_string(),
+                    package_name.as_normalized().to_string(),
+                );
+            }
+        }
+
+        Self { library_to_package }
+    }
+
+    /// Look up a library path by extracting its filename and checking the map.
+    /// Returns the package name if found.
+    ///
+    /// Handles various library path forms:
+    /// - Plain filenames: `libz.so.1`
+    /// - macOS @rpath references: `@rpath/libz.1.dylib`
+    /// - Full or relative paths: `lib/libz.so.1`
+    pub fn find_package(&self, library: &Path) -> Option<PackageName> {
+        let path_str = library.to_string_lossy();
+
+        // Strip @rpath/ or @loader_path/ prefixes (macOS)
+        let stripped = path_str
+            .strip_prefix("@rpath/")
+            .or_else(|| path_str.strip_prefix("@loader_path/"))
+            .unwrap_or(&path_str);
+
+        // Try the stripped path directly (handles plain filenames)
+        if let Some(pkg) = self.library_to_package.get(stripped) {
+            return PackageName::try_from(pkg.as_str()).ok();
+        }
+
+        // Try just the filename component
+        let file_name = Path::new(stripped).file_name()?.to_string_lossy();
+
+        self.library_to_package
+            .get(file_name.as_ref())
+            .and_then(|n| PackageName::try_from(n.as_str()).ok())
+    }
+
+    /// Returns true if the map is empty.
+    pub fn is_empty(&self) -> bool {
+        self.library_to_package.is_empty()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;