zlayer-builder 0.14.0

//! 3-tier macOS image resolution system
//!
//! On macOS, Linux container images cannot run natively. This module implements
//! a resolution pipeline that rewrites Docker Hub image references to macOS-native
//! equivalents:
//!
//! 1. **GHCR pre-built images**: Check if a pre-built macOS sandbox image exists
//!    at `ghcr.io/blackleafdigital/zlayer/{language}:{version}`.
//! 2. **Local toolchain build**: Install the toolchain directly (Go, Node, Rust,
//!    etc.) via `macos_toolchain` and assemble a sandbox rootfs.
//! 3. **Base image fallback**: For distro images (ubuntu, alpine, etc.) just
//!    create a minimal macOS rootfs with host binaries.
//!
//! Additionally provides Homebrew bottle fetching for installing packages into
//! sandbox rootfs on macOS (replacing `apt-get`/`apk` from Linux Dockerfiles).

use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::str::FromStr;

use serde::{Deserialize, Serialize};
use tracing::{debug, info, warn};
use zlayer_types::toolchain_lock::ToolchainLockfile;
use zlayer_types::ImageReference;

use crate::error::{BuildError, Result};
use crate::macos_toolchain::{
    ensure_base_rootfs, extract_version_from_tag, provision_toolchain, ToolchainSpec,
};
use crate::sandbox_builder::SandboxImageConfig;

/// Install a Homebrew formula into a sandbox build rootfs by provisioning a
/// self-contained **keg** (via `zlayer-toolchain` — source build for the
/// homebrew-core C-tool population, or a relocation-free prebuilt fetch for the
/// language toolchains) and materializing it under `{rootfs}/usr/local`.
///
/// This replaces the dead-end Homebrew **bottle** path (download a prebuilt
/// bottle and rewrite its baked `@@HOMEBREW_PREFIX@@` install-name
/// placeholders). That rewrite was length-preserving and left embedded
/// `@@HOMEBREW@@` `LC_LOAD_DYLIB` paths, so the binary aborted under a Seatbelt
/// container (where those paths don't exist and macOS strips `DYLD_*`). A keg
/// is built at an absolute prefix, so every load command is an absolute system
/// library or absolute keg path — never `@@HOMEBREW@@`.
///
/// The keg's binaries are copied (symlinks preserved) into `{rootfs}/usr/local`
/// so the build's PATH (`{rootfs}/usr/local/bin`) finds them. For the
/// self-contained C-tool population this is sufficient — the binaries link only
/// absolute macOS system libraries and run standalone from the copied location.
///
/// When `lockfile` is `Some`, a lock hit for the tool pins the exact version +
/// URL and the download is verified against the pinned sha256; a miss
/// live-resolves. The lock is loaded once by the sandbox builder and threaded
/// down the execute chain.
///
/// # Errors
///
/// Propagates keg provisioning errors (formula resolution / download / build)
/// and I/O errors while copying the keg into the rootfs.
pub async fn install_formula_into_rootfs(
    formula: &str,
    rootfs_dir: &Path,
    cache_dir: &Path,
    lockfile: Option<&ToolchainLockfile>,
) -> Result<()> {
    let handle = zlayer_toolchain::ensure_toolchain(
        formula,
        zlayer_toolchain::ToolPlatform::MacOS,
        cache_dir,
        lockfile,
    )
    .await?;
    materialize_keg_into_rootfs(&handle.install_dir, rootfs_dir).await
}

/// Copy a provisioned keg's payload subtrees into `{rootfs}/usr/local`,
/// preserving symlinks. Only the subtrees a tool needs at runtime are copied
/// (`bin`, `sbin`, `lib`, `libexec`, `include`, `share`); the keg's
/// `toolchain.json`/`.ready`/`.build` metadata is skipped.
async fn materialize_keg_into_rootfs(keg: &Path, rootfs_dir: &Path) -> Result<()> {
    let dest_prefix = rootfs_dir.join("usr/local");
    tokio::fs::create_dir_all(&dest_prefix).await?;

    for sub in ["bin", "sbin", "lib", "libexec", "include", "share"] {
        let src = keg.join(sub);
        if !tokio::fs::try_exists(&src).await.unwrap_or(false) {
            continue;
        }
        let dest = dest_prefix.join(sub);
        tokio::fs::create_dir_all(&dest).await?;
        // `cp -R` (BSD) preserves symlinks and merges into an existing dir when
        // the source is given as `src/.`. Reuse the host `cp` so we don't
        // hand-roll a recursive copy that mishandles symlinked dylibs.
        let status = tokio::process::Command::new("cp")
            .arg("-R")
            .arg(format!("{}/.", src.display()))
            .arg(&dest)
            .status()
            .await?;
        if !status.success() {
            return Err(BuildError::IoError(std::io::Error::other(format!(
                "failed to copy keg subtree {} into rootfs at {}",
                src.display(),
                dest.display()
            ))));
        }
    }
    Ok(())
}

/// The `GHCR` registry prefix for pre-built `ZLayer` sandbox images.
const ZLAYER_REGISTRY: &str = "ghcr.io/blackleafdigital/zlayer";

/// Base URL for fetching package mapping files from `RepoSources` (`GitHub Pages`).
const REPO_SOURCES_BASE: &str = "https://zachhandley.github.io/RepoSources/maps";

/// How long a cached package-map file is considered fresh (7 days).
const PACKAGE_MAP_CACHE_TTL_SECS: u64 = 7 * 24 * 3600;

/// Subdirectory name (under the platform cache dir) where per-distro shard
/// files are stored. Bumped from `package-maps-v2` to invalidate caches
/// that pre-date the cross-distro `common/` shard set + zombie-purging
/// generator overwrite — old caches still serve unversioned `openssl`,
/// `python`, `node` for cross-distro names (e.g. centos's `libssl-dev`).
/// Old dirs are abandoned, not migrated.
const PACKAGE_MAP_CACHE_SUBDIR: &str = "package-maps-v3";

// ---------------------------------------------------------------------------
// Package map types (for RepoSources JSON files)
// ---------------------------------------------------------------------------

/// A package mapping file as published by `RepoSources`.
#[derive(Debug, Deserialize, Serialize)]
struct PackageMapFile {
    metadata: PackageMapMetadata,
    mappings: HashMap<String, String>,
}

/// Metadata header inside a package-map JSON file.
#[derive(Debug, Deserialize, Serialize)]
struct PackageMapMetadata {
    generated_at: String,
    source: String,
    distro: String,
    /// Shard letter (`a`-`z` or `_misc`) for sharded files. `None` for
    /// hand-written test fixtures or pre-sharding archives.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    shard: Option<String>,
    total_mappings: usize,
}

// ---------------------------------------------------------------------------
// macOS base-image classification + optional prebuilt cache
// ---------------------------------------------------------------------------

/// What kind of macOS-native base a Linux `FROM` maps to under Seatbelt.
///
/// A Linux base image (`golang:1.25`, `ubuntu:24.04`, …) can't execute under
/// the macOS sandbox, so for a darwin-native build we provision an equivalent
/// natively. This is the *classification* — it does NOT rewrite the user's
/// image reference to some other registry.
#[derive(Debug, Clone)]
pub enum MacBaseKind {
    /// A language toolchain image (golang/node/rust/…) provisioned natively via
    /// [`crate::macos_toolchain`].
    Toolchain(ToolchainSpec),
    /// A base distro (ubuntu/alpine/debian/…) — a minimal macOS rootfs.
    BaseDistro,
}

/// Classify a Linux base image into its macOS-native equivalent.
///
/// Returns `None` when the image is not a known toolchain or base distro — it
/// is then resolved normally (local store / local registry / upstream pull).
/// This is pure classification: no image reference is rewritten.
#[must_use]
pub fn classify_macos_base(image_ref: &str) -> Option<MacBaseKind> {
    // Images already provisioned into our own cache namespace aren't reclassified.
    if image_ref.starts_with(ZLAYER_REGISTRY) {
        return None;
    }
    if let Some(spec) = crate::macos_toolchain::detect_toolchain(image_ref) {
        return Some(MacBaseKind::Toolchain(spec));
    }
    let stripped = strip_registry_prefix(image_ref);
    let name = match ImageReference::from_str(&stripped) {
        Ok(r) => r.repository().to_string(),
        Err(_) => stripped.clone(),
    };
    let base_name = name.rsplit('/').next().unwrap_or(&name);
    if is_base_distro(base_name) {
        return Some(MacBaseKind::BaseDistro);
    }
    None
}

/// Derive the OPTIONAL prebuilt-cache reference for a classified base image.
///
/// This is **not** a resolution rewrite of the user's image — it is only a
/// local cache key and the target of a best-effort, anonymous **public** pull
/// from the prebuilt namespace (`ghcr.io/blackleafdigital/zlayer/*`). A miss is
/// never fatal: the base is then provisioned locally, which is the resolution
/// of record. Returns `None` for images we don't special-case.
///
/// # Examples
///
/// ```ignore
/// assert_eq!(
///     prebuilt_cache_ref("golang:1.23-alpine"),
///     Some("ghcr.io/blackleafdigital/zlayer/golang:1.23".to_string()),
/// );
/// assert_eq!(
///     prebuilt_cache_ref("ubuntu:22.04"),
///     Some("ghcr.io/blackleafdigital/zlayer/base:latest".to_string()),
/// );
/// ```
#[must_use]
pub fn prebuilt_cache_ref(image_ref: &str) -> Option<String> {
    if image_ref.starts_with(ZLAYER_REGISTRY) {
        return None;
    }

    // Strip the registry prefix (docker.io/library/, ghcr.io/foo/, etc.)
    let stripped = strip_registry_prefix(image_ref);

    // Split into name and tag using the canonical parser (handles host:port,
    // digests, and missing tags correctly).
    let (name, tag) = match ImageReference::from_str(&stripped) {
        Ok(r) => (
            r.repository().to_string(),
            r.tag().unwrap_or("latest").to_string(),
        ),
        Err(_) => (stripped.clone(), "latest".to_string()),
    };
    let base_name = name.rsplit('/').next().unwrap_or(&name);

    // Base distro images → base:latest
    if is_base_distro(base_name) {
        return Some(format!("{ZLAYER_REGISTRY}/base:latest"));
    }

    // Toolchain images → {zlayer_registry}/{canonical}:{version}
    let canonical = match base_name {
        "golang" | "go" => "golang",
        "node" => "node",
        "rust" => "rust",
        "python" | "python3" => "python",
        "deno" => "deno",
        "bun" => "bun",
        "swift" => "swift",
        "zig" => "zig",
        "eclipse-temurin" | "amazoncorretto" | "openjdk" => "java",
        name if name.contains("graalvm") => "graalvm",
        _ => return None,
    };

    let version = extract_version_from_tag(&tag);
    Some(format!("{ZLAYER_REGISTRY}/{canonical}:{version}"))
}

/// Check whether the given base image name is a Linux distribution / base image.
fn is_base_distro(name: &str) -> bool {
    matches!(
        name,
        "ubuntu"
            | "debian"
            | "alpine"
            | "centos"
            | "fedora"
            | "rockylinux"
            | "almalinux"
            | "archlinux"
            | "amazonlinux"
            | "busybox"
    )
}

/// Strip common registry prefixes from an image reference.
fn strip_registry_prefix(image_ref: &str) -> String {
    let prefixes = [
        "docker.io/library/",
        "docker.io/",
        "index.docker.io/library/",
        "index.docker.io/",
    ];
    for prefix in &prefixes {
        if let Some(rest) = image_ref.strip_prefix(prefix) {
            return rest.to_string();
        }
    }
    image_ref.to_string()
}

// ---------------------------------------------------------------------------
// GHCR authentication
// ---------------------------------------------------------------------------

/// Resolve authentication credentials for GHCR.
///
/// Checks, in order:
/// 1. `GHCR_TOKEN` environment variable
/// 2. `GITHUB_TOKEN` environment variable
/// 3. Docker config file (`~/.docker/config.json`) for saved `ghcr.io` creds
/// 4. Falls back to `Anonymous`
pub fn resolve_ghcr_auth() -> zlayer_registry::RegistryAuth {
    use zlayer_registry::RegistryAuth;

    // 1. GHCR_TOKEN
    if let Ok(token) = std::env::var("GHCR_TOKEN") {
        if !token.is_empty() {
            debug!("Using GHCR_TOKEN for registry auth");
            return RegistryAuth::Basic("_token".to_string(), token);
        }
    }

    // 2. GITHUB_TOKEN
    if let Ok(token) = std::env::var("GITHUB_TOKEN") {
        if !token.is_empty() {
            debug!("Using GITHUB_TOKEN for registry auth");
            return RegistryAuth::Basic("_token".to_string(), token);
        }
    }

    // 3. Docker config
    if let Some(creds) = read_docker_config_ghcr_auth() {
        debug!("Using Docker config credentials for GHCR");
        return creds;
    }

    // 4. Anonymous
    debug!("No GHCR credentials found, using anonymous auth");
    RegistryAuth::Anonymous
}

/// Attempt to read GHCR credentials from `~/.docker/config.json`.
fn read_docker_config_ghcr_auth() -> Option<zlayer_registry::RegistryAuth> {
    use base64::prelude::*;
    use zlayer_registry::RegistryAuth;

    let home = dirs::home_dir()?;
    let config_path = home.join(".docker").join("config.json");
    let contents = std::fs::read_to_string(&config_path).ok()?;
    let config: serde_json::Value = serde_json::from_str(&contents).ok()?;

    let auth_b64 = config.get("auths")?.get("ghcr.io")?.get("auth")?.as_str()?;

    let decoded = BASE64_STANDARD.decode(auth_b64).ok()?;
    let decoded_str = String::from_utf8(decoded).ok()?;

    let (user, pass) = decoded_str.split_once(':')?;
    Some(RegistryAuth::Basic(user.to_string(), pass.to_string()))
}

// ---------------------------------------------------------------------------
// Tier 1: Pull pre-built image from GHCR
// ---------------------------------------------------------------------------

/// Try to pull a pre-built `ZLayer` sandbox image from `GHCR`.
///
/// Returns `Ok(true)` if the image was successfully pulled and extracted,
/// `Ok(false)` if the image could not be pulled (auth failure, not found,
/// network error, etc.). Errors are logged as warnings but never propagated
/// — the caller should fall through to the next resolution tier.
///
/// # Errors
///
/// Returns an error if directory creation or layer unpacking fails with an
/// unrecoverable I/O error.
#[cfg(feature = "cache")]
pub async fn try_pull_zlayer_image(
    image_ref: &str,
    image_dir: &Path,
    rootfs_dir: &Path,
) -> Result<bool> {
    use zlayer_registry::{BlobCache, ImagePuller, LayerUnpacker};

    info!("Attempting to pull ZLayer image: {}", image_ref);

    let cache = match BlobCache::new() {
        Ok(c) => c,
        Err(e) => {
            warn!("Failed to create blob cache for GHCR pull: {e}");
            return Ok(false);
        }
    };
    let puller = ImagePuller::new(cache);
    let auth = resolve_ghcr_auth();

    // Ensure directories exist
    tokio::fs::create_dir_all(rootfs_dir).await?;

    // Stream layers to files (no full layer buffered in RAM); stage is a sibling
    // of the rootfs (same filesystem, so hardlinks work).
    let layer_stage = {
        let mut s = rootfs_dir.as_os_str().to_owned();
        s.push(".layers.tmp");
        std::path::PathBuf::from(s)
    };
    let _ = tokio::fs::remove_dir_all(&layer_stage).await;
    let layers = match puller
        .pull_image_to_files(image_ref, &auth, &layer_stage)
        .await
    {
        Ok(l) => l,
        Err(e) => {
            warn!("Failed to pull ZLayer image {image_ref}: {e}");
            let _ = tokio::fs::remove_dir_all(&layer_stage).await;
            return Ok(false);
        }
    };

    info!(
        "Pulled {} layers for {}, extracting to rootfs",
        layers.len(),
        image_ref
    );

    // Unpack layers, streaming each from disk.
    let mut unpacker = LayerUnpacker::new(rootfs_dir.to_path_buf());
    let unpack_result = unpacker.unpack_layers_from_files(&layers).await;
    let _ = tokio::fs::remove_dir_all(&layer_stage).await;
    if let Err(e) = unpack_result {
        warn!("Failed to unpack layers for {image_ref}: {e}");
        return Ok(false);
    }

    // Pull and save image config if possible
    match puller.pull_image_config(image_ref, &auth).await {
        Ok(ic) => {
            if let Ok(json) = serde_json::to_string_pretty(&ic) {
                let _ = tokio::fs::write(image_dir.join("image_config.json"), json).await;
            }
        }
        Err(e) => debug!("Could not pull image config for {image_ref}: {e}"),
    }

    info!(
        "Successfully pulled and extracted ZLayer image: {}",
        image_ref
    );
    Ok(true)
}

// ---------------------------------------------------------------------------
// Tier 2: Build toolchain as a local image
// ---------------------------------------------------------------------------

/// Build a sandbox image by installing the toolchain locally.
///
/// Creates an image directory at `data_dir/images/{sanitized_name}/` containing
/// a `rootfs/` with host binaries and the provisioned toolchain, plus a
/// `config.json` with appropriate environment variables.
///
/// # Errors
///
/// Returns an error if directory creation, toolchain provisioning, or config
/// serialization fails.
pub async fn build_toolchain_as_image(
    spec: &ToolchainSpec,
    image_ref: &str,
    data_dir: &Path,
) -> Result<PathBuf> {
    let image_name = sanitize_image_name(image_ref);
    let image_dir = data_dir.join("images").join(&image_name);
    let rootfs_dir = image_dir.join("rootfs");

    tokio::fs::create_dir_all(&rootfs_dir).await?;

    // Lay down the base rootfs (host binaries, SSL certs, directory structure)
    ensure_base_rootfs(&rootfs_dir).await?;

    // Provision the toolchain into the rootfs
    let cache_dir = data_dir.join("toolchain-cache");
    let tmp_dir = data_dir.join("tmp");
    tokio::fs::create_dir_all(&cache_dir).await?;
    tokio::fs::create_dir_all(&tmp_dir).await?;

    provision_toolchain(spec, &rootfs_dir, &cache_dir, &tmp_dir).await?;

    // Write config.json (include source hash for cache invalidation)
    let mut config = toolchain_spec_to_config(spec);
    {
        use sha2::{Digest, Sha256};
        let mut hasher = Sha256::new();
        hasher.update(format!("{spec:?}").as_bytes());
        config.source_hash = Some(format!("{:x}", hasher.finalize()));
    }
    let config_json =
        serde_json::to_string_pretty(&config).map_err(|e| BuildError::CacheError {
            message: format!("failed to serialise image config: {e}"),
        })?;
    tokio::fs::write(image_dir.join("config.json"), config_json).await?;

    info!(
        "Built toolchain image for {} v{} at {}",
        spec.language,
        spec.version,
        image_dir.display()
    );
    Ok(image_dir)
}

// ---------------------------------------------------------------------------
// Tier 3: Base image (distro) fallback
// ---------------------------------------------------------------------------

/// Build a minimal base image (no toolchain) for distro images like ubuntu/alpine.
///
/// Creates a rootfs with host binaries, SSL certs, and a default config.
///
/// # Errors
///
/// Returns an error if directory creation, base rootfs setup, or config
/// serialization fails.
pub async fn build_base_image(image_ref: &str, data_dir: &Path) -> Result<PathBuf> {
    let image_name = sanitize_image_name(image_ref);
    let image_dir = data_dir.join("images").join(&image_name);
    let rootfs_dir = image_dir.join("rootfs");

    tokio::fs::create_dir_all(&rootfs_dir).await?;

    // Lay down the base rootfs
    ensure_base_rootfs(&rootfs_dir).await?;

    // Write a default config.json (include source hash for cache invalidation)
    let source_hash = {
        use sha2::{Digest, Sha256};
        let mut hasher = Sha256::new();
        hasher.update(format!("base_image:{image_ref}").as_bytes());
        format!("{:x}", hasher.finalize())
    };
    let config = SandboxImageConfig {
        env: vec![
            "PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin".to_string(),
            "HOME=/root".to_string(),
        ],
        working_dir: "/".to_string(),
        entrypoint: None,
        cmd: Some(vec!["/bin/sh".to_string()]),
        exposed_ports: HashMap::new(),
        labels: HashMap::new(),
        user: None,
        volumes: Vec::new(),
        stop_signal: None,
        shell: None,
        healthcheck: None,
        source_hash: Some(source_hash),
    };
    let config_json =
        serde_json::to_string_pretty(&config).map_err(|e| BuildError::CacheError {
            message: format!("failed to serialise image config: {e}"),
        })?;
    tokio::fs::write(image_dir.join("config.json"), config_json).await?;

    info!("Built base image at {}", image_dir.display());
    Ok(image_dir)
}

// ---------------------------------------------------------------------------
// Config conversion
// ---------------------------------------------------------------------------

/// Convert a [`ToolchainSpec`] into a [`SandboxImageConfig`].
///
/// Maps the spec's environment variables and PATH directories into the
/// container-style config format used by the sandbox builder.
#[must_use]
pub fn toolchain_spec_to_config(spec: &ToolchainSpec) -> SandboxImageConfig {
    // Build environment variables
    let mut env: Vec<String> = spec.env.iter().map(|(k, v)| format!("{k}={v}")).collect();

    // Build PATH from spec.path_dirs + standard paths
    let mut path_parts: Vec<&str> = spec.path_dirs.iter().map(String::as_str).collect();
    path_parts.extend(["/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"]);
    let path_value = path_parts.join(":");
    env.push(format!("PATH={path_value}"));

    env.push("HOME=/root".to_string());

    SandboxImageConfig {
        env,
        working_dir: "/".to_string(),
        entrypoint: None,
        cmd: Some(vec!["/bin/sh".to_string()]),
        exposed_ports: HashMap::new(),
        labels: HashMap::new(),
        user: None,
        volumes: Vec::new(),
        stop_signal: None,
        shell: None,
        healthcheck: None,
        source_hash: None,
    }
}

// ---------------------------------------------------------------------------
// Linux package name mapping
// ---------------------------------------------------------------------------

/// Map Linux package names (apt/apk) to Homebrew formula names.
///
/// Resolution order for each package:
/// 1. Cached/fetched package map from `RepoSources` (`{cache_dir}/package-maps-v2/debian.json`)
/// 2. Name transformation heuristics (strip `-dev`, `lib` prefix, version digits)
/// 3. Hardcoded fallback mapping
///
/// Returns a vec of `(linux_name, brew_formula, skipped)` tuples. `linux_name`
/// is preserved for error reporting. `skipped` is `true` for packages that are
/// Linux-only and have no macOS equivalent (e.g. `musl-dev`, `ca-certificates`).
pub async fn map_linux_packages(
    packages: &[&str],
    distro: &str,
    cache_dir: &Path,
) -> Vec<(String, String, bool)> {
    let map = load_or_fetch_package_map(distro, packages, cache_dir).await;

    packages
        .iter()
        .map(|&pkg| {
            let (brew, skipped) = resolve_single_package(pkg, distro, &map);
            (pkg.to_string(), brew, skipped)
        })
        .collect()
}

/// Resolve a single Linux package name to a `(brew_formula, skipped)` pair.
///
/// Tries the remote/cached map first, then name transformations, then the
/// hardcoded fallback. `distro` (e.g. `debian_12`/`alpine_3_20`) is only used
/// to report a genuinely-unmapped package to `ZPackageIndex` at the
/// pass-through site (step 4) so the index can backfill the mapping.
fn resolve_single_package(
    pkg: &str,
    distro: &str,
    map: &HashMap<String, String>,
) -> (String, bool) {
    // 1. Check if it's a Linux-only skip package (always hardcoded — these never
    //    have a brew equivalent).
    if is_linux_only_package(pkg) {
        return (pkg.to_string(), true);
    }

    // 2. Look up in the RepoSources map.
    if let Some(brew) = map.get(pkg) {
        return (brew.clone(), false);
    }

    // 3. Try name transformations and look those up in the map.
    if let Some(brew) = try_name_transforms(pkg, map) {
        return (brew, false);
    }

    // 4. Genuine MISS: the index has no mapping for this Linux package and no
    //    name transform hit, so we pass the Linux name through as-is. Fire a
    //    cheap fire-and-forget "unfulfilled request" so the server-side hourly
    //    scheduler can backfill the mapping (a future native build then
    //    resolves it without the VM fallback). `apk` for alpine, else `apt`;
    //    distro normalized `debian_12` -> `debian-12`.
    let manager = if distro.starts_with("alpine") {
        "apk"
    } else {
        "apt"
    };
    crate::harvest::report_unfulfilled(&distro.replacen('_', "-", 1), manager, pkg);

    map_single_package_hardcoded(pkg)
}

/// Returns `true` for packages that are Linux-only and should be skipped on macOS.
//
// Force-skipped Linux-only names. Some entries here (gcc, make, gnupg,
// procps) do exist as brew formulas, but installing them on macOS would
// shadow Apple's system toolchain or duplicate already-present binaries.
// We intentionally drop these from the install set rather than mapping
// them through brew. If a user genuinely needs the brew version they
// can ask for it by brew name explicitly (e.g. `brew install gcc@14`).
/// (a) Packages macOS makes moot — safe to skip as a build no-op (no Homebrew
/// install, and the RUN step that asked for them is faithfully a no-op on macOS).
pub(crate) fn is_macos_irrelevant_package(pkg: &str) -> bool {
    matches!(
        pkg,
        "ca-certificates"
            | "apt-transport-https"
            | "software-properties-common"
            | "procps"
            // installed almost exclusively for apt-key verification, which
            // does not exist on macOS:
            | "gnupg"
            | "gnupg2"
    )
}

/// (b) Packages that demand a real Linux toolchain / libc / kernel headers — a
/// macOS sandbox cannot satisfy these via a Homebrew bottle, so a build that
/// installs them must fall back to the buildd-in-VZ Linux path rather than skip
/// the step (the skip would be a silent false-success).
pub(crate) fn is_linux_toolchain_package(pkg: &str) -> bool {
    matches!(
        pkg,
        "build-essential"
            | "gcc"
            | "g++"
            | "make"
            | "musl-dev"
            | "musl-tools"
            | "musl"
            | "libc-dev"
            | "libc6-dev"
            | "linux-headers"
            | "linux-headers-generic"
    )
}

/// Union — both classes are "skipped" by the resolver (neither gets a brew
/// install). The sandbox build step distinguishes them: irrelevant → no-op,
/// toolchain → raise `BuildError::SandboxNeedsLinux`.
fn is_linux_only_package(pkg: &str) -> bool {
    is_macos_irrelevant_package(pkg) || is_linux_toolchain_package(pkg)
}

/// Try common Linux-to-Homebrew name transformations and look the result up
/// in the map.
///
/// Transformations attempted (in order):
/// 1. Strip `-dev` suffix
/// 2. Strip `lib` prefix
/// 3. Strip both `lib` prefix and `-dev` suffix
/// 4. Remove trailing version digits (e.g. `libfoo3` -> `libfoo`)
fn try_name_transforms(pkg: &str, map: &HashMap<String, String>) -> Option<String> {
    // Strip -dev suffix
    if let Some(base) = pkg.strip_suffix("-dev") {
        if let Some(brew) = map.get(base) {
            return Some(brew.clone());
        }
    }

    // Strip lib prefix
    if let Some(rest) = pkg.strip_prefix("lib") {
        if let Some(brew) = map.get(rest) {
            return Some(brew.clone());
        }

        // Strip both lib prefix and -dev suffix
        if let Some(base) = rest.strip_suffix("-dev") {
            if let Some(brew) = map.get(base) {
                return Some(brew.clone());
            }
        }
    }

    // Remove trailing version digits (e.g. "zlib1g" -> "zlib", "libfoo3" -> "libfoo")
    let without_digits = pkg.trim_end_matches(|c: char| c.is_ascii_digit() || c == '.');
    if without_digits != pkg && !without_digits.is_empty() {
        if let Some(brew) = map.get(without_digits) {
            return Some(brew.clone());
        }
        // Also try without trailing 'g' (e.g. "zlib1g-dev" already handled by -dev strip)
        let without_g = without_digits.trim_end_matches('g');
        if without_g != without_digits && !without_g.is_empty() {
            if let Some(brew) = map.get(without_g) {
                return Some(brew.clone());
            }
        }
    }

    None
}

/// Hardcoded fallback mapping for a single Linux package to its Homebrew
/// equivalent. This is the safety net when the `RepoSources` map is unavailable
/// or doesn't contain the package.
fn map_single_package_hardcoded(pkg: &str) -> (String, bool) {
    // Pass-through: when RepoSources is unreachable AND name transforms
    // miss, hand the Linux name to the keg provisioner as-is. Phase 2's
    // dynamic resolution in scripts/generate-package-maps.py:pick_winner
    // produces the right brew formula name (including `@MAJOR` pins like
    // openssl@3); the prior hardcoded fallback table (libssl-dev →
    // openssl, python3 → python@3, etc.) actively contradicted that
    // output and would 404 for alias-only names like python@3.
    (pkg.to_string(), false)
}

/// Compute the shard key for a package name.
///
/// Mirrors the sharding rule used by `scripts/generate-package-maps.py`:
/// the lowercase first ASCII letter if `a..z`, otherwise `_misc`. Empty
/// strings also map to `_misc`.
fn shard_key(name: &str) -> &'static str {
    let first = name.chars().next().map(|c| c.to_ascii_lowercase());
    match first {
        Some(c) if c.is_ascii_lowercase() => match c {
            'a' => "a",
            'b' => "b",
            'c' => "c",
            'd' => "d",
            'e' => "e",
            'f' => "f",
            'g' => "g",
            'h' => "h",
            'i' => "i",
            'j' => "j",
            'k' => "k",
            'l' => "l",
            'm' => "m",
            'n' => "n",
            'o' => "o",
            'p' => "p",
            'q' => "q",
            'r' => "r",
            's' => "s",
            't' => "t",
            'u' => "u",
            'v' => "v",
            'w' => "w",
            'x' => "x",
            'y' => "y",
            'z' => "z",
            _ => "_misc",
        },
        _ => "_misc",
    }
}

/// Load the package mappings for a distro, fetching the relevant per-letter
/// shards from `RepoSources` if not cached or stale.
///
/// Cascading lookup: for each shard letter implied by `packages`, fetch
/// both `common/<shard>.json` (cross-distro consensus) AND
/// `<distro>/<shard>.json` (distro-specific, more authoritative). Merge
/// with **per-distro winning** on conflict — distro-specific is a tighter
/// answer when known; common is the fallback for names that distro
/// doesn't have (e.g. `libssl-dev` on centos).
async fn load_or_fetch_package_map(
    distro: &str,
    packages: &[&str],
    cache_dir: &Path,
) -> HashMap<String, String> {
    let cache_root = cache_dir.join(PACKAGE_MAP_CACHE_SUBDIR);
    let common_cache_dir = cache_root.join("common");
    let distro_cache_dir = cache_root.join(distro);

    let mut shards: HashSet<&'static str> = HashSet::new();
    for pkg in packages {
        shards.insert(shard_key(pkg));
    }

    let mut common_merged: HashMap<String, String> = HashMap::new();
    let mut distro_merged: HashMap<String, String> = HashMap::new();

    for shard in shards {
        if let Some(map) = fetch_or_load_shard("common", &common_cache_dir, shard).await {
            common_merged.extend(map);
        }
        if let Some(map) = fetch_or_load_shard(distro, &distro_cache_dir, shard).await {
            distro_merged.extend(map);
        }
    }

    // Per-distro values WIN over common — distro is more specific. Insertion
    // order: common first, distro overrides on conflict.
    let mut merged = common_merged;
    merged.extend(distro_merged);
    merged
}

/// Fetch one shard for a label (`<distro>` or `"common"`), with on-disk
/// cache + stale fallback. Returns `None` only when there's no fresh
/// fetch, no usable stale cache — i.e. truly nothing available.
async fn fetch_or_load_shard(
    label: &str,
    cache_dir: &Path,
    shard: &str,
) -> Option<HashMap<String, String>> {
    let cache_path = cache_dir.join(format!("{shard}.json"));

    // 1. Fresh local cache.
    if let Ok(meta) = tokio::fs::metadata(&cache_path).await {
        if let Ok(modified) = meta.modified() {
            // `elapsed()` errs only when `modified` is in the FUTURE relative to
            // `SystemTime::now()`. That's exactly a *just-written* cache file:
            // the file's mtime clock and the wall clock can skew by a few
            // microseconds (common on APFS), leaving a brand-new file dated
            // slightly ahead of `now()`. Such a file is the freshest possible —
            // treat it as age 0. The previous `u64::MAX` fallback did the
            // opposite: it flagged a freshly-written shard as maximally stale,
            // forcing a live RepoSources HTTP fetch whose response overwrote the
            // just-cached (or test-seeded) shard on disk — a spurious network
            // round-trip and a non-hermetic clobber of a cache we should trust.
            let age = modified.elapsed().unwrap_or(std::time::Duration::ZERO);
            if age.as_secs() < PACKAGE_MAP_CACHE_TTL_SECS {
                if let Some(map) = read_cached_map(&cache_path).await {
                    debug!(
                        "Using cached package map for {label}/{shard} ({} mappings, age {}s)",
                        map.len(),
                        age.as_secs()
                    );
                    return Some(map);
                }
            }
        }
    }

    // 2. Fetch from RepoSources.
    let url = format!("{REPO_SOURCES_BASE}/{label}/{shard}.json");
    debug!("Fetching package map shard from {url}");

    match fetch_package_map(&url).await {
        Ok(map_file) => {
            info!(
                "Fetched {} package mappings for {label}/{shard} from RepoSources",
                map_file.mappings.len()
            );
            if let Err(e) = write_cached_map(cache_dir, &cache_path, &map_file).await {
                warn!("Failed to cache package map for {label}/{shard}: {e}");
            }
            Some(map_file.mappings)
        }
        Err(e) => {
            debug!("Failed to fetch package map for {label}/{shard}: {e}");

            // 3. Stale cache fallback.
            if let Some(map) = read_cached_map(&cache_path).await {
                info!(
                    "Using stale cached package map for {label}/{shard} ({} mappings)",
                    map.len()
                );
                return Some(map);
            }

            // 4. Nothing — caller (load_or_fetch_package_map) will quietly
            //    proceed with whatever's already merged. A blanket warning
            //    here would fire for every shard miss in `common/` even
            //    when the per-distro shard succeeds; let the resolver-level
            //    miss path produce the user-facing message.
            None
        }
    }
}

/// Fetch a `PackageMapFile` from the given URL.
async fn fetch_package_map(url: &str) -> std::result::Result<PackageMapFile, String> {
    let response = reqwest::get(url)
        .await
        .map_err(|e| format!("HTTP request failed: {e}"))?;

    if !response.status().is_success() {
        return Err(format!("HTTP {}", response.status()));
    }

    response
        .json::<PackageMapFile>()
        .await
        .map_err(|e| format!("JSON parse failed: {e}"))
}

/// Read a cached package-map file from disk and return just the mappings.
async fn read_cached_map(path: &Path) -> Option<HashMap<String, String>> {
    let contents = tokio::fs::read_to_string(path).await.ok()?;
    let map_file: PackageMapFile = serde_json::from_str(&contents).ok()?;
    Some(map_file.mappings)
}

/// Write a `PackageMapFile` to disk, creating the directory if needed.
async fn write_cached_map(
    map_dir: &Path,
    cache_path: &Path,
    map_file: &PackageMapFile,
) -> std::result::Result<(), String> {
    tokio::fs::create_dir_all(map_dir)
        .await
        .map_err(|e| format!("create dir: {e}"))?;

    let json = serde_json::to_string_pretty(map_file).map_err(|e| format!("serialize: {e}"))?;

    tokio::fs::write(cache_path, json)
        .await
        .map_err(|e| format!("write: {e}"))
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Sanitize an image reference for use as a directory name.
fn sanitize_image_name(image: &str) -> String {
    image.replace(['/', ':', '@'], "_")
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use zlayer_paths::ZLayerDirs;

    // -- prebuilt_cache_ref tests --

    #[test]
    fn test_rewrite_golang() {
        let result = prebuilt_cache_ref("golang:1.23");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/golang:1.23")));
    }

    #[test]
    fn test_rewrite_golang_alpine() {
        let result = prebuilt_cache_ref("golang:1.23-alpine");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/golang:1.23")));
    }

    #[test]
    fn test_rewrite_ubuntu_to_base() {
        let result = prebuilt_cache_ref("ubuntu:22.04");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/base:latest")));
    }

    #[test]
    fn test_rewrite_alpine_to_base() {
        let result = prebuilt_cache_ref("alpine:3.19");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/base:latest")));
    }

    #[test]
    fn test_rewrite_node_latest() {
        let result = prebuilt_cache_ref("node:latest");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/node:latest")));
    }

    #[test]
    fn test_rewrite_node_slim() {
        let result = prebuilt_cache_ref("node:20-slim");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/node:20")));
    }

    #[test]
    fn test_rewrite_python_bookworm() {
        let result = prebuilt_cache_ref("python:3.12-bookworm");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/python:3.12")));
    }

    #[test]
    fn test_rewrite_qualified_golang() {
        let result = prebuilt_cache_ref("docker.io/library/golang:1.22");
        assert_eq!(result, Some(format!("{ZLAYER_REGISTRY}/golang:1.22")));
    }

    #[test]
    fn test_no_rewrite_custom_image() {
        let result = prebuilt_cache_ref("myregistry.io/myteam/myapp:v1.0");
        assert_eq!(result, None);
    }

    #[test]
    fn test_no_rewrite_already_zlayer() {
        let result = prebuilt_cache_ref("ghcr.io/blackleafdigital/zlayer/golang:1.23");
        assert_eq!(result, None);
    }

    // -- toolchain_spec_to_config tests --

    #[test]
    fn test_toolchain_spec_to_config_go() {
        let spec = ToolchainSpec::go("1.23");
        let config = toolchain_spec_to_config(&spec);

        // Should have GOROOT, GOFLAGS, PATH, HOME
        assert!(config.env.iter().any(|e| e.starts_with("GOROOT=")));
        assert!(config.env.iter().any(|e| e.starts_with("PATH=")));

        // PATH should include go bin dir
        let path_entry = config.env.iter().find(|e| e.starts_with("PATH=")).unwrap();
        assert!(path_entry.contains("/usr/local/go/bin"));

        assert_eq!(config.working_dir, "/");
    }

    #[test]
    fn test_toolchain_spec_to_config_java() {
        let spec = ToolchainSpec::java("21");
        let config = toolchain_spec_to_config(&spec);

        assert!(config.env.iter().any(|e| e.starts_with("JAVA_HOME=")));

        let path_entry = config.env.iter().find(|e| e.starts_with("PATH=")).unwrap();
        assert!(path_entry.contains("/usr/local/java/bin"));
    }

    // -- map_linux_packages / resolve_single_package tests --

    #[test]
    fn test_resolve_common_packages_hardcoded() {
        let empty_map = HashMap::new();
        for pkg in &["curl", "git", "wget", "jq"] {
            let (name, skipped) = resolve_single_package(pkg, "debian_12", &empty_map);
            assert!(!skipped, "{pkg} should not be skipped");
            assert_eq!(name, *pkg);
        }
    }

    #[test]
    fn test_resolve_skip_linux_only() {
        let empty_map = HashMap::new();
        for pkg in &["build-essential", "ca-certificates", "musl-dev", "libc-dev"] {
            let (_name, skipped) = resolve_single_package(pkg, "debian_12", &empty_map);
            assert!(skipped, "{pkg} should be skipped");
        }
    }

    #[test]
    fn test_resolve_passthrough_unknown() {
        let empty_map = HashMap::new();
        let (name, skipped) =
            resolve_single_package("some-obscure-package", "debian_12", &empty_map);
        assert_eq!(name, "some-obscure-package");
        assert!(!skipped);
    }

    #[test]
    fn test_resolve_with_remote_map() {
        let mut map = HashMap::new();
        map.insert("libfoo-dev".to_string(), "foo".to_string());
        map.insert("custom-pkg".to_string(), "custom-brew".to_string());

        // Direct match from map
        let (name, skipped) = resolve_single_package("custom-pkg", "debian_12", &map);
        assert_eq!(name, "custom-brew");
        assert!(!skipped);

        // Direct match from map (with -dev suffix)
        let (name, skipped) = resolve_single_package("libfoo-dev", "debian_12", &map);
        assert_eq!(name, "foo");
        assert!(!skipped);
    }

    #[test]
    fn test_resolve_name_transforms() {
        let mut map = HashMap::new();
        map.insert("ssl".to_string(), "openssl".to_string());
        map.insert("yaml".to_string(), "libyaml".to_string());

        // Strip lib prefix to find "ssl" in map
        let (name, _) = resolve_single_package("libssl", "debian_12", &map);
        assert_eq!(name, "openssl");

        // Strip lib prefix + -dev suffix to find "yaml" in map
        let (name, _) = resolve_single_package("libyaml-dev", "debian_12", &map);
        assert_eq!(name, "libyaml");
    }

    /// Live smoke test against the published `RepoSources` JSON.
    ///
    /// Hits live `RepoSources` (`https://zachhandley.github.io/RepoSources/maps/...`)
    /// and asserts the canonical Homebrew names. Stays `#[ignore]` because
    /// it's network-bound and brew rotates default majors yearly; pattern
    /// match the verify-reposources.yml globs (`openssl@3`, `node@<MAJOR>`).
    #[tokio::test]
    #[ignore = "live network test; runs against published RepoSources"]
    async fn test_map_linux_packages_live_reposources() {
        let tmp = ZLayerDirs::system_default()
            .tmp()
            .join("zlayer-test-pkg-map-live");
        let _ = tokio::process::Command::new("chmod")
            .args(["-R", "u+w"])
            .arg(&tmp)
            .status()
            .await;
        let _ = tokio::process::Command::new("rm")
            .args(["-rf"])
            .arg(&tmp)
            .status()
            .await;

        let result =
            map_linux_packages(&["curl", "libssl-dev", "musl-dev"], "debian_12", &tmp).await;
        assert_eq!(result.len(), 3);
        assert_eq!(result[0].0, "curl");
        assert_eq!(result[0].1, "curl");
        assert!(!result[0].2);
        assert_eq!(result[1].0, "libssl-dev");
        assert_eq!(result[1].1, "openssl@3");
        assert!(!result[1].2);
        assert_eq!(result[2].0, "musl-dev");
        assert!(result[2].2);

        let _ = tokio::process::Command::new("chmod")
            .args(["-R", "u+w"])
            .arg(&tmp)
            .status()
            .await;
        let _ = tokio::process::Command::new("rm")
            .args(["-rf"])
            .arg(&tmp)
            .status()
            .await;
    }

    /// Hermetic test: writes per-shard fixture `PackageMapFile`s to disk, then
    /// verifies `map_linux_packages` returns the expected
    /// `(linux_name, brew, skipped)` triples. No network. Always runs in CI —
    /// this is the regression guard for the sharded layout.
    async fn write_shard(
        label_dir: &Path,
        label: &str,
        shard: &str,
        mappings: HashMap<String, String>,
    ) {
        tokio::fs::create_dir_all(label_dir)
            .await
            .expect("create label dir");
        let fixture = PackageMapFile {
            metadata: PackageMapMetadata {
                generated_at: "2026-04-29T00:00:00Z".to_string(),
                source: "test-fixture".to_string(),
                distro: label.to_string(),
                shard: Some(shard.to_string()),
                total_mappings: mappings.len(),
            },
            mappings,
        };
        let json = serde_json::to_string_pretty(&fixture).expect("serialize fixture");
        tokio::fs::write(label_dir.join(format!("{shard}.json")), json)
            .await
            .expect("write shard fixture");
    }

    #[tokio::test]
    async fn test_map_linux_packages_with_seeded_cache() {
        let tmp = ZLayerDirs::system_default()
            .scratch_dir("test-map-linux-packages-with-seeded-cache-")
            .expect("create tmpdir");
        let cache_dir = tmp.path().to_path_buf();
        let cache_root = cache_dir.join(PACKAGE_MAP_CACHE_SUBDIR);
        let distro_dir = cache_root.join("debian_12");

        let mut c_mappings = HashMap::new();
        c_mappings.insert("curl".to_string(), "curl".to_string());
        write_shard(&distro_dir, "debian_12", "c", c_mappings).await;

        let mut l_mappings = HashMap::new();
        l_mappings.insert("libssl-dev".to_string(), "openssl@3".to_string());
        write_shard(&distro_dir, "debian_12", "l", l_mappings).await;

        let mut n_mappings = HashMap::new();
        n_mappings.insert("nodejs".to_string(), "node@24".to_string());
        write_shard(&distro_dir, "debian_12", "n", n_mappings).await;

        let result = map_linux_packages(
            &["curl", "libssl-dev", "musl-dev", "nodejs"],
            "debian_12",
            &cache_dir,
        )
        .await;

        assert_eq!(result.len(), 4);
        assert_eq!(result[0].0, "curl");
        assert_eq!(result[0].1, "curl");
        assert!(!result[0].2);
        assert_eq!(result[1].0, "libssl-dev");
        assert_eq!(result[1].1, "openssl@3");
        assert!(!result[1].2);
        assert_eq!(result[2].0, "musl-dev");
        assert!(result[2].2);
        assert_eq!(result[3].0, "nodejs");
        assert_eq!(result[3].1, "node@24");
        assert!(!result[3].2);
    }

    /// Cascading lookup: a name absent from the per-distro shard but
    /// present in `common/` should resolve via the common fallback.
    /// Models the real-world case where centos's `l.json` doesn't list
    /// `libssl-dev` (debian-only name) but `common/l.json` does.
    #[tokio::test]
    async fn test_map_linux_packages_falls_back_to_common() {
        let tmp = ZLayerDirs::system_default()
            .scratch_dir("test-map-linux-packages-falls-back-to-common-")
            .expect("create tmpdir");
        let cache_dir = tmp.path().to_path_buf();
        let cache_root = cache_dir.join(PACKAGE_MAP_CACHE_SUBDIR);
        let distro_dir = cache_root.join("centos_8");
        let common_dir = cache_root.join("common");

        // centos_8 has its own openssl-devel mapping but NOT libssl-dev.
        let mut distro_o = HashMap::new();
        distro_o.insert("openssl-devel".to_string(), "openssl@3".to_string());
        write_shard(&distro_dir, "centos_8", "o", distro_o).await;

        // common/l.json carries the cross-distro libssl-dev mapping, sourced
        // from debian's view.
        let mut common_l = HashMap::new();
        common_l.insert("libssl-dev".to_string(), "openssl@3".to_string());
        write_shard(&common_dir, "common", "l", common_l).await;

        // Hermetic guards: seed empty shards for every (label, shard) pair the
        // resolver will probe but isn't deliberately populated above. Without
        // these, fetch_or_load_shard falls through to a live RepoSources HTTP
        // request whose response can clobber the seeded values (per-distro
        // wins on conflict in the merge). Probed shards: o (openssl-devel)
        // and l (libssl-dev) for both common/ and centos_8/.
        write_shard(&common_dir, "common", "o", HashMap::new()).await;
        write_shard(&distro_dir, "centos_8", "l", HashMap::new()).await;

        let result =
            map_linux_packages(&["openssl-devel", "libssl-dev"], "centos_8", &cache_dir).await;

        assert_eq!(result.len(), 2);
        assert_eq!(result[0].0, "openssl-devel");
        assert_eq!(result[0].1, "openssl@3");
        assert!(!result[0].2);
        // libssl-dev resolves via common, even though centos_8's `l` shard
        // wasn't seeded.
        assert_eq!(result[1].0, "libssl-dev");
        assert_eq!(result[1].1, "openssl@3");
        assert!(!result[1].2);
    }

    /// Cascading lookup: when both per-distro AND `common/` define the
    /// same name with different values, per-distro wins. Per-distro is
    /// the more-specific source of truth for that distro.
    #[tokio::test]
    async fn test_map_linux_packages_distro_overrides_common() {
        let tmp = ZLayerDirs::system_default()
            .scratch_dir("test-map-linux-packages-distro-overrides-common-")
            .expect("create tmpdir");
        let cache_dir = tmp.path().to_path_buf();
        let cache_root = cache_dir.join(PACKAGE_MAP_CACHE_SUBDIR);
        let distro_dir = cache_root.join("alpine_3_20");
        let common_dir = cache_root.join("common");

        let mut distro_p = HashMap::new();
        distro_p.insert("python3".to_string(), "python@3.13".to_string());
        write_shard(&distro_dir, "alpine_3_20", "p", distro_p).await;

        let mut common_p = HashMap::new();
        common_p.insert("python3".to_string(), "python@3.14".to_string());
        write_shard(&common_dir, "common", "p", common_p).await;

        let result = map_linux_packages(&["python3"], "alpine_3_20", &cache_dir).await;

        assert_eq!(result.len(), 1);
        assert_eq!(result[0].0, "python3");
        // Per-distro wins (3.13), not common's 3.14.
        assert_eq!(result[0].1, "python@3.13");
        assert!(!result[0].2);
    }

    /// Regression: a freshly-written shard whose mtime lands slightly in the
    /// FUTURE relative to `SystemTime::now()` (wall-clock vs filesystem-timestamp
    /// skew — routinely a few microseconds on APFS) must still count as a fresh
    /// cache hit and NOT be re-fetched over the network. The prior
    /// `unwrap_or(u64::MAX)` freshness fallback flipped such a file to
    /// "maximally stale", firing a live `RepoSources` fetch whose response
    /// overwrote the seeded shard on disk — the non-hermetic clobber that made
    /// `test_map_linux_packages_falls_back_to_common` flake. We force a future
    /// mtime on the (guarded) probed shards and assert the seeded mapping
    /// survives with no network round-trip.
    #[tokio::test]
    async fn test_future_mtime_shard_is_fresh_not_refetched() {
        let tmp = ZLayerDirs::system_default()
            .scratch_dir("test-future-mtime-shard-")
            .expect("create tmpdir");
        let cache_dir = tmp.path().to_path_buf();
        let cache_root = cache_dir.join(PACKAGE_MAP_CACHE_SUBDIR);
        let distro_dir = cache_root.join("centos_8");
        let common_dir = cache_root.join("common");

        let mut distro_o = HashMap::new();
        distro_o.insert("openssl-devel".to_string(), "openssl@3".to_string());
        write_shard(&distro_dir, "centos_8", "o", distro_o).await;
        // Guard the sibling common/o shard so it, too, cannot reach the network.
        write_shard(&common_dir, "common", "o", HashMap::new()).await;

        // Force both probed shards' mtime one hour into the future so
        // `modified.elapsed()` returns Err — the exact condition the fix must
        // treat as "fresh" rather than "stale".
        let future = std::time::SystemTime::now() + std::time::Duration::from_secs(3600);
        for p in [distro_dir.join("o.json"), common_dir.join("o.json")] {
            let f = std::fs::File::options()
                .write(true)
                .open(&p)
                .expect("open shard for mtime bump");
            f.set_modified(future).expect("set future mtime");
        }

        let result = map_linux_packages(&["openssl-devel"], "centos_8", &cache_dir).await;
        assert_eq!(result.len(), 1);
        assert_eq!(result[0].0, "openssl-devel");
        assert_eq!(result[0].1, "openssl@3");
        assert!(!result[0].2);
    }
}