zlayer_toolchain/

source_build.rs

//! Build runtime toolchains **from source** into a self-contained, absolute
//! cache toolchain — "our apt-get" for the macOS sandbox, which has no package
//! manager.
//!
//! # Why source-build instead of a Homebrew bottle
//!
//! Relocating a Homebrew *bottle* (rewriting its baked `@@HOMEBREW_PREFIX@@`
//! install-name placeholders) is a dead end: the rewrite is length-preserving
//! and silently skips placeholders shorter than the cache prefix, so the toolchain's
//! binary keeps `@@HOMEBREW_PREFIX@@/...` `LC_LOAD_DYLIB` paths. Under a darwin
//! Seatbelt container those paths don't exist and macOS strips `DYLD_*` from
//! the signed binary, so dyld aborts (`Symbol not found … Abort trap: 6`).
//!
//! Building from source at an absolute toolchain prefix sidesteps both failure modes:
//! every `LC_LOAD_DYLIB` is an absolute path to a macOS system library
//! (`/usr/lib/...`) or an absolute sibling-toolchain path — never `@@HOMEBREW@@` — and
//! the compiled `sysconfdir`/`prefix` live inside the toolchain, so the tool reads its
//! own config instead of `/etc/*` (which EPERMs under the deny-default profile).
//!
//! # A fully generic, data-driven build
//!
//! There is **no per-formula recipe table**. Everything the build needs is
//! derived from the Homebrew formula JSON we already parse plus the extracted
//! source tree:
//!
//! - **Dependencies come from the formula's data.** Anything in
//!   `uses_from_macos` is provided by macOS itself (the Seatbelt profile already
//!   grants `/usr/lib` + `/usr/include` via the Command Line Tools) so it is
//!   skipped. Every *other* `dependency` / `build_dependency` is resolved
//!   **recursively** as a sibling toolchain via [`crate::ensure_macos_toolchain`] and wired
//!   onto the build with *absolute* toolchain paths — build tools land on `PATH`,
//!   libraries contribute `-I<toolchain>/include` / `-L<toolchain>/lib` /
//!   `-Wl,-rpath,<toolchain>/lib` / `PKG_CONFIG_PATH=<toolchain>/lib/pkgconfig`. So git's
//!   `gettext`/`pcre2` and jq's `oniguruma` become resolved toolchains automatically —
//!   no `NO_GETTEXT`, no `--with-oniguruma=builtin`, no hardcoded skip lists.
//! - **The build system is autodetected** from the extracted tree (a generated
//!   `configure`, a `CMake` self-host `bootstrap`, a `CMakeLists.txt`, a bare
//!   `Makefile`, or an autotools project shipped as `configure.ac`).
//! - **Irreducible env is derived from the install layout, not the name.** A toolchain
//!   that installed `<toolchain>/libexec/git-core` gets `GIT_EXEC_PATH` pointed there —
//!   true for any git-exec-helper tool, asserted by layout, never by `== "git"`.
//!
//! # Strategy order
//!
//! [`ensure_from_source`] routes each formula through up to three strategies:
//!
//! 1. **Parsed-recipe container build** — when the runtime has registered a
//!    [`crate::executor::ContainerBuildExecutor`], the formula's real
//!    `def install` is fetched and parsed into a typed
//!    [`crate::recipe::InstallPlan`]; a fully-supported plan executes inside an
//!    isolated container with the network **denied** (source tarball, resources
//!    and patches are pre-fetched and sha-verified leaf-side). With no executor
//!    registered this strategy — including the recipe fetch itself — is skipped
//!    entirely, so executor-less processes behave exactly as before.
//! 2. **The generic autodetected build** described above.
//! 3. **Brew-emulate**: if the generic build fails (a custom `install do` /
//!    patches the generic build can't reproduce), [`crate::brew_emulate`] runs
//!    the formula's *real* Homebrew recipe at the toolchain prefix — so
//!    genuinely-custom formulae still work with **zero** hardcoding.

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

use tracing::{debug, info, warn};

use crate::error::{Result, ToolchainError};
use crate::executor::{ContainerBuildExecutor, ContainerBuildRequest, NetPolicy};
use crate::formula::{self, Formula};
use crate::manifest::{ToolchainManifest, ToolchainSource};
use crate::recipe::{InstallPlan, RecipeCtx, ResourceSpec};
use crate::registry::ToolchainArtifactId;
use crate::relocate::RelocationReport;

/// The macOS platform token stored in an artifact id / coverage record.
const MACOS_OS_TOKEN: &str = "macos";

/// Which build strategy produced a toolchain, for coverage + publish routing.
///
/// The choice IS the net-fallback signal: `NetFallback` is only reachable via
/// the `brew_emulate` branch, which runs (with the network allowed loudly) only
/// after both the container-recipe and generic strategies have failed.
enum BuildKind {
    /// A hermetic build (container-recipe or generic) won: the toolchain was
    /// relocated (report attached) and is publishable → coverage `Built`.
    Hermetic(RelocationReport),
    /// The `brew_emulate` loud full-network fallback won → coverage `NetFallback`
    /// (not hermetic, not published).
    NetFallback,
}

/// Resolved source-build coordinates for a tool.
#[derive(Debug, Clone)]
pub struct SourceSpec {
    /// Stable version string (e.g. `2.55.0`).
    pub version: String,
    /// URL of the source tarball.
    pub tarball_url: String,
    /// The source tarball's sha256 (bare hex, `sha256:` prefix stripped). Empty
    /// when the formula publishes no `urls.stable.checksum`.
    pub sha256: String,
    /// Runtime dependency formula names.
    pub dependencies: Vec<String>,
    /// Build-only dependency formula names.
    pub build_dependencies: Vec<String>,
    /// Dependency names macOS itself provides (need no toolchain).
    pub macos_provided: Vec<String>,
}

/// Which build system a recipe drives, autodetected from the extracted tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum BuildSystem {
    /// `./configure --prefix=<toolchain> && make && make install` (a generated
    /// `configure`, or `configure.ac`/`autogen.sh` regenerated first).
    Autotools,
    /// `cmake -DCMAKE_INSTALL_PREFIX=<toolchain> … && cmake --build && cmake --install`
    /// using a `cmake` resolved as a build-dependency toolchain.
    CMake,
    /// A self-hosting `CMake` (`bootstrap` + `CMakeLists.txt`, i.e. cmake itself):
    /// `./bootstrap --prefix=<toolchain> --parallel=N && make && make install`.
    CMakeBootstrap,
    /// A bare hand-written `Makefile`: `make prefix=<toolchain> … install`.
    MakePrefix,
}

/// Host architecture token used in cache keys (`arm64` / `x86_64`).
fn arch_token() -> &'static str {
    match std::env::consts::ARCH {
        "aarch64" => "arm64",
        other => other,
    }
}

/// Fetch the formula and extract its source-build coordinates.
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] if the formula cannot be fetched
/// or carries no stable version / source URL.
pub async fn resolve_source_spec(formula: &str) -> Result<SourceSpec> {
    let info: Formula = formula::fetch_formula(formula).await?;

    let version = info
        .stable_version()
        .ok_or_else(|| ToolchainError::RegistryError {
            message: format!("formula {formula} has no stable version"),
        })?
        .to_string();

    let tarball_url = info
        .stable_url()
        .ok_or_else(|| ToolchainError::RegistryError {
            message: format!("formula {formula} has no stable source URL"),
        })?
        .to_string();

    Ok(SourceSpec {
        version,
        tarball_url,
        sha256: info.stable_checksum().unwrap_or_default(),
        dependencies: info.dependencies.clone(),
        build_dependencies: info.build_dependencies.clone(),
        macos_provided: info.macos_provided(),
    })
}

/// Build `formula` from source into a self-contained toolchain under `cache_dir`,
/// writing a [`ToolchainManifest`] and returning the toolchain path.
///
/// Idempotent: a `<toolchain>/.ready` marker (written LAST, after the manifest)
/// short-circuits a populated toolchain. A cold build removes any partial toolchain, builds
/// into a scratch dir, installs into the toolchain prefix, writes the manifest, then
/// stamps `.ready`.
///
/// Strategy order: parsed-recipe container build (only when a runtime
/// [`crate::executor::ContainerBuildExecutor`] is registered) → generic
/// autodetected build → brew-emulate. See the module docs.
///
/// # Errors
///
/// Propagates formula-resolution, download, extraction, dependency, and build
/// failures.
pub async fn ensure_from_source(
    formula: &str,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
) -> Result<PathBuf> {
    let mut spec = resolve_source_spec(formula).await?;

    // A lock hit pins the exact version + source URL + digest (consume-only).
    // The dependency graph still comes from the resolved formula.
    if let Some(locked) = lockfile.and_then(|l| {
        use crate::ToolchainLockfileExt;
        l.lookup(formula, "macos", arch_token())
    }) {
        spec.version = locked.version.clone();
        spec.tarball_url = locked.url.clone();
        spec.sha256 = locked.sha256.clone();
    }

    let toolchain = cache_dir.join(format!("{formula}-{}-{}", spec.version, arch_token()));
    let ready_marker = toolchain.join(".ready");

    // Local `.ready` wins FIRST: a locally-present toolchain short-circuits with
    // zero network (no pull, no coverage).
    if tokio::fs::try_exists(&ready_marker).await.unwrap_or(false) {
        return Ok(toolchain);
    }

    // Identity is known now (version resolved above). Try the registry before
    // building — best-effort; a miss or transport error just falls through.
    let id = ToolchainArtifactId {
        tool: formula.to_string(),
        version: spec.version.clone(),
        os: MACOS_OS_TOKEN.to_string(),
        arch: arch_token().to_string(),
    };
    if crate::pull_first(&id, &toolchain).await?.is_some() {
        return Ok(toolchain);
    }

    // Miss → build, then record coverage + (for a hermetic build) publish.
    // Coverage is recorded EXACTLY ONCE on every terminal outcome.
    match run_build_chain(formula, &spec, &toolchain, cache_dir, lockfile).await {
        Ok(BuildKind::Hermetic(report)) => {
            crate::finish_built(&id, &toolchain, Some(&report), false).await;
            Ok(toolchain)
        }
        Ok(BuildKind::NetFallback) => {
            crate::record_net_fallback(&id).await;
            Ok(toolchain)
        }
        Err(e) => {
            crate::record_failed(&id, &e).await;
            Err(e)
        }
    }
}

/// Run the source-build strategy chain: parsed-recipe container build (only when
/// a runtime executor is registered) → generic autodetected build →
/// `brew_emulate`. Returns which strategy won ([`BuildKind`]) so the caller can
/// route coverage + publish; propagates a terminal build error.
async fn run_build_chain(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
) -> Result<BuildKind> {
    // Strategy 1: the formula's REAL recipe, parsed into a typed plan and
    // executed inside an isolated container (network denied, all inputs
    // pre-fetched leaf-side). Gated on a registered runtime executor — an
    // executor-less process skips this entirely (no recipe fetch, no extra
    // network) and behaves exactly as it did before this route existed.
    if let Some(executor) = crate::executor::container_executor() {
        match try_recipe_container_build(
            formula,
            spec,
            toolchain,
            cache_dir,
            lockfile,
            executor.as_ref(),
        )
        .await
        {
            Ok(report) => return Ok(BuildKind::Hermetic(report)),
            Err(e) => {
                if matches!(e, ToolchainError::ExecutorUnavailable { .. }) {
                    // Expected until the runtime registers an executor;
                    // not a coverage gap worth a warning.
                    debug!(
                        formula,
                        error = %e,
                        "container executor unavailable; falling through to the generic source build"
                    );
                } else {
                    warn!(
                        formula,
                        error = %e,
                        "container recipe build failed; falling through to the generic source build"
                    );
                }
                // Drop any partial container-route state so the generic build
                // (and, after it, brew-emulate) starts from a clean prefix.
                let _ = tokio::fs::remove_dir_all(toolchain).await;
            }
        }
    }

    // Try the generic build next. If it can't build this formula — no build
    // system detected (a custom `install do` with no
    // `configure`/`CMakeLists.txt`/`Makefile`, e.g. a `cargo install` / `go
    // build` formula), a required dependency toolchain won't build, or the build
    // errors in a way the generic flags don't cover — fall back to running the
    // formula's REAL Homebrew recipe at the toolchain prefix (`brew_emulate`).
    match try_generic_source_build(formula, spec, toolchain, cache_dir, lockfile).await {
        Ok(report) => Ok(BuildKind::Hermetic(report)),
        Err(e) => {
            warn!(
                formula,
                error = %e,
                "generic source build failed; falling back to brew-emulate at the toolchain prefix"
            );
            // Drop the partial generic toolchain so the brew-emulate install starts
            // from a clean prefix (it reuses the same `<toolchain>` cache key).
            let _ = tokio::fs::remove_dir_all(toolchain).await;
            // The loud full-network fallback: `brew_emulate` (AllowLoud) → NetFallback.
            crate::brew_emulate::ensure_via_brew(formula, spec, cache_dir).await?;
            Ok(BuildKind::NetFallback)
        }
    }
}

/// Attempt the recipe-plan container route: resolve dependencies, fetch and
/// parse the formula's real `def install`, and — when the plan is fully
/// supported — execute it in the runtime container `executor`.
///
/// Any error (dependency resolution, recipe fetch/parse, unsupported
/// constructs, resource pre-fetch, executor failure) makes the caller fall
/// through to the generic-build → brew-emulate chain unchanged.
async fn try_recipe_container_build(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
    executor: &dyn ContainerBuildExecutor,
) -> Result<RelocationReport> {
    // Fresh attempt: a crashed prior attempt must not leave a half-populated
    // prefix that confuses the container install.
    let _ = tokio::fs::remove_dir_all(toolchain).await;
    tokio::fs::create_dir_all(toolchain).await?;
    let scratch = toolchain.join(".build");
    tokio::fs::create_dir_all(&scratch).await?;

    // 1. Dependencies FIRST: the plan's `Formula["x"].opt_*` references resolve
    //    through each dep's toolchain prefix.
    let deps = resolve_dependencies(formula, spec, cache_dir, lockfile).await?;

    // 2. Fetch + parse the recipe. `SourceSpec` is a distilled projection that
    //    does not retain the `FormulaData` (`ruby_source_path` in particular),
    //    so re-fetch it through the package index (cheap, cached server-side).
    let info: Formula = formula::fetch_formula(formula).await?;
    let rb = crate::recipe::fetch_recipe_cached(&info, &scratch.join("recipe.rb")).await?;
    let ctx = RecipeCtx {
        tool: formula.to_string(),
        version: spec.version.clone(),
        prefix: toolchain.to_path_buf(),
        dep_prefixes: deps.prefixes_by_name.clone(),
        target_macos: true,
        target_arm: arch_token() == "arm64",
    };
    let plan = crate::recipe::parse_install_plan(&rb, &ctx)?;

    // 3. Route only fully-supported plans to the container; surface every
    //    unsupported construct individually so coverage gaps are visible.
    if !plan.is_fully_supported() {
        let constructs: Vec<String> = plan
            .unsupported_constructs()
            .into_iter()
            .map(str::to_string)
            .collect();
        for construct in &constructs {
            warn!(
                formula,
                construct = %construct,
                "recipe construct unsupported by the native interpreter"
            );
        }
        return Err(ToolchainError::RecipeUnsupported {
            tool: formula.to_string(),
            constructs,
        });
    }

    execute_plan_in_container(formula, spec, toolchain, plan, &deps, executor).await
}

/// Execute a fully-supported [`InstallPlan`] in the runtime container:
/// download + extract the source, pre-fetch every resource/patch
/// (sha-verified — the container runs with the network DENIED), run the plan,
/// then finish the toolchain exactly like the generic build does (manifest,
/// scratch cleanup, `.ready` stamped LAST).
async fn execute_plan_in_container(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    plan: InstallPlan,
    deps: &ResolvedDeps,
    executor: &dyn ContainerBuildExecutor,
) -> Result<RelocationReport> {
    let scratch = toolchain.join(".build");
    let src_dir = download_and_extract(formula, spec, &scratch).await?;
    let resources_dir = prefetch_plan_inputs(formula, &plan, &scratch).await?;
    let req = assemble_container_request(
        formula,
        toolchain,
        &scratch,
        plan,
        deps,
        src_dir,
        resources_dir,
    );
    run_request_and_finalize(spec, deps.build_dep_names.clone(), req, executor).await
}

/// Run an assembled [`ContainerBuildRequest`] through `executor` and, on
/// success, finish the toolchain (manifest + `.ready`) exactly the way
/// [`try_generic_source_build`] finishes — via the shared
/// [`finalize_toolchain`].
async fn run_request_and_finalize(
    spec: &SourceSpec,
    build_dep_names: Vec<String>,
    req: ContainerBuildRequest,
    executor: &dyn ContainerBuildExecutor,
) -> Result<RelocationReport> {
    let report = executor.execute(&req).await?;
    debug!(tool = %req.tool, log_tail = %report.log_tail, "container recipe build succeeded");
    finalize_toolchain(
        &req.tool,
        spec,
        &req.prefix,
        &req.scratch_dir,
        build_dep_names,
        &req.dep_toolchains,
    )
    .await
}

/// Assemble the [`ContainerBuildRequest`] for a fully-supported plan: network
/// denied (all inputs pre-fetched), dependency toolchain bins on `PATH`
/// (mirroring the generic build's [`run_cmd`] PATH assembly, where dep
/// toolchain bins come first), and the plan's accumulated env merged
/// (+ `MAKEFLAGS=-j1` when the recipe deparallelizes).
fn assemble_container_request(
    formula: &str,
    toolchain: &Path,
    scratch: &Path,
    plan: InstallPlan,
    deps: &ResolvedDeps,
    src_dir: PathBuf,
    resources_dir: Option<PathBuf>,
) -> ContainerBuildRequest {
    let env = plan_env(&plan);
    ContainerBuildRequest {
        tool: formula.to_string(),
        platform: crate::ToolPlatform::MacOS,
        plan,
        src_dir,
        prefix: toolchain.to_path_buf(),
        scratch_dir: scratch.to_path_buf(),
        dep_toolchains: deps.prefixes.clone(),
        resources_dir,
        env,
        path_prefix: deps.env.path_prefix.clone(),
        net: NetPolicy::Deny,
    }
}

/// The container environment for a plan: the plan's accumulated `ENV` sets,
/// plus `MAKEFLAGS=-j1` when the recipe called `ENV.deparallelize` (overriding
/// any recipe-set `MAKEFLAGS` — deparallelize is an explicit "this build
/// races under parallel make").
fn plan_env(plan: &InstallPlan) -> HashMap<String, String> {
    let mut env = plan.env.clone();
    if plan.deparallelize {
        env.insert("MAKEFLAGS".to_string(), "-j1".to_string());
    }
    env
}

/// Pre-fetch staging destination for a named recipe resource:
/// `<resources_dir>/<name>/<url-basename>` (the same basename derivation
/// [`download_and_extract`] uses for the source tarball).
fn resource_dest(resources_dir: &Path, res: &ResourceSpec) -> PathBuf {
    let file = res
        .url
        .rsplit('/')
        .next()
        .filter(|s| !s.is_empty())
        .unwrap_or("resource.tar");
    resources_dir.join(&res.name).join(file)
}

/// Pre-fetch staging destination for `plan.patches[index]`:
/// `<resources_dir>/patches/<index>`.
fn patch_dest(resources_dir: &Path, index: usize) -> PathBuf {
    resources_dir.join("patches").join(index.to_string())
}

/// Pre-fetch every resource + patch of `plan` into `<scratch>/resources`
/// (sha256-verified — the container runs with the network DENIED, so every
/// input must land here first). Returns `None` when the plan declares neither.
///
/// # Errors
///
/// A resource/patch with an empty sha256 is an error on this path: Homebrew
/// formulae always publish digests (the weak-checksum case is Chocolatey-only
/// and never reaches this macOS route), so an empty digest means a parse gap —
/// refuse the unverified download rather than staging it silently.
async fn prefetch_plan_inputs(
    formula: &str,
    plan: &InstallPlan,
    scratch: &Path,
) -> Result<Option<PathBuf>> {
    if plan.resources.is_empty() && plan.patches.is_empty() {
        return Ok(None);
    }
    let resources_dir = scratch.join("resources");

    for res in &plan.resources {
        if res.sha256.trim().is_empty() {
            return Err(ToolchainError::RegistryError {
                message: format!(
                    "resource '{}' of {formula} declares no sha256; refusing an unverified pre-fetch",
                    res.name
                ),
            });
        }
        let dest = resource_dest(&resources_dir, res);
        crate::package_index::download_verified(&res.url, &dest, Some(&res.sha256)).await?;
    }

    for (index, patch) in plan.patches.iter().enumerate() {
        if patch.sha256.trim().is_empty() {
            return Err(ToolchainError::RegistryError {
                message: format!(
                    "patch #{index} of {formula} declares no sha256; refusing an unverified pre-fetch"
                ),
            });
        }
        let dest = patch_dest(&resources_dir, index);
        crate::package_index::download_verified(&patch.url, &dest, Some(&patch.sha256)).await?;
    }

    Ok(Some(resources_dir))
}

/// Attempt the generic (autotools/CMake/Makefile) source build into `toolchain`.
///
/// On success the toolchain is fully populated: manifest written and `.ready` stamped.
/// On any failure (detection or build) the caller falls back to
/// [`crate::brew_emulate`]. Kept as a separate fallible step so the fallback
/// decision is a single `match` at the call site.
async fn try_generic_source_build(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
) -> Result<RelocationReport> {
    // Fresh build. Remove any partial toolchain so a crashed prior attempt can't leave
    // a half-installed prefix that confuses the installer.
    let _ = tokio::fs::remove_dir_all(toolchain).await;
    tokio::fs::create_dir_all(toolchain).await?;

    let scratch = toolchain.join(".build");
    tokio::fs::create_dir_all(&scratch).await?;

    // 1. Resolve dependencies as sibling toolchains and assemble the build env. macOS-
    //    provided deps (`uses_from_macos`) are skipped; everything else is built
    //    recursively as a toolchain with absolute paths.
    let deps = resolve_dependencies(formula, spec, cache_dir, lockfile).await?;

    // 2. Download + extract the source tarball into `<scratch>/src`.
    let src_dir = download_and_extract(formula, spec, &scratch).await?;

    // 3. Autodetect the build system and run it into the toolchain prefix.
    let system = detect_build_system(&src_dir).await?;
    info!(formula, ?system, "detected build system");
    run_build(formula, &src_dir, toolchain, system, &deps.env).await?;

    // 4. Relocate + write the manifest + stamp `.ready`, returning the report.
    finalize_toolchain(
        formula,
        spec,
        toolchain,
        &scratch,
        deps.build_dep_names,
        &deps.prefixes,
    )
    .await
}

/// Finish a successfully-populated toolchain the single canonical way (shared
/// by the container-recipe and generic build paths):
///
/// 1. clean the scratch dir FIRST (so relocation walks only the installed tree,
///    never the build's intermediate objects),
/// 2. [`make_relocatable`](crate::relocate::make_relocatable) the tree in place
///    (built prefix = the toolchain dir; `dep_dirs` = the resolved dependency
///    toolchains) — rewriting Mach-O load commands + text placeholders and
///    returning the [`RelocationReport`] the publish step consumes,
/// 3. write the [`ToolchainManifest`] AFTER relocation (so its absolute
///    `path_dirs` are not themselves placeholdered), then stamp `.ready` LAST.
async fn finalize_toolchain(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    scratch: &Path,
    build_deps: Vec<String>,
    dep_dirs: &[PathBuf],
) -> Result<RelocationReport> {
    // Clean scratch before relocating so the relocation pass sees only the
    // installed toolchain tree. A NotFound (already clean) is fine; only a real
    // failure warns.
    match tokio::fs::remove_dir_all(scratch).await {
        Ok(()) => {}
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
        Err(e) => warn!(error = %e, "failed to clean source scratch dir (non-fatal)"),
    }

    let report = crate::relocate::make_relocatable(toolchain, toolchain, dep_dirs).await?;

    let manifest = build_manifest(formula, spec, toolchain, build_deps).await;
    manifest.write_to_toolchain(toolchain).await?;
    tokio::fs::write(toolchain.join(".ready"), b"").await?;

    Ok(report)
}

/// Build the [`ToolchainManifest`] for a freshly-installed source toolchain, deriving any
/// irreducible runtime env from the **installed layout** (never the formula
/// name): a toolchain that produced `<toolchain>/libexec/git-core` gets `GIT_EXEC_PATH`
/// pointed there, so git discovers its exec-helpers out of the toolchain.
async fn build_manifest(
    formula: &str,
    spec: &SourceSpec,
    toolchain: &Path,
    build_deps: Vec<String>,
) -> ToolchainManifest {
    let mut path_dirs = Vec::new();
    let bin = toolchain.join("bin");
    if tokio::fs::try_exists(&bin).await.unwrap_or(false) {
        path_dirs.push(bin.display().to_string());
    }

    let mut env: HashMap<String, String> = HashMap::new();
    // Layout-derived, not name-derived: any tool that installs git's exec-helper
    // dir needs `GIT_EXEC_PATH` to find them out of the toolchain rather than the host.
    let git_exec = toolchain.join("libexec/git-core");
    if tokio::fs::try_exists(&git_exec).await.unwrap_or(false) {
        env.insert("GIT_EXEC_PATH".to_string(), git_exec.display().to_string());
    }

    ToolchainManifest {
        tool: formula.to_string(),
        version: spec.version.clone(),
        arch: arch_token().to_string(),
        platform: "macos".to_string(),
        path_dirs,
        env,
        source: ToolchainSource::SourceBuild {
            url: spec.tarball_url.clone(),
            sha256: spec.sha256.clone(),
        },
        build_deps,
        provisioned_at: chrono::Utc::now().to_rfc3339(),
    }
}

/// Environment accumulated for a source build: `PATH` plus linker/include/
/// pkg-config flags pointing at resolved dependency toolchains.
#[derive(Debug, Default, Clone)]
struct BuildEnv {
    path_prefix: Vec<String>,
    cppflags: Vec<String>,
    ldflags: Vec<String>,
    pkg_config_path: Vec<String>,
}

/// Dependency material resolved for a source build: the accumulated
/// [`BuildEnv`], the build-dep names recorded in the manifest, and each
/// resolved dependency's toolchain prefix (feeding
/// [`RecipeCtx::dep_prefixes`] and the container's read/exec grants).
#[derive(Debug, Default)]
struct ResolvedDeps {
    /// `PATH` / `CPPFLAGS` / `LDFLAGS` / `PKG_CONFIG_PATH` from dep toolchains.
    env: BuildEnv,
    /// Build-dependency formula names (recorded in the toolchain manifest).
    build_dep_names: Vec<String>,
    /// Formula name → resolved toolchain prefix (build + runtime deps).
    prefixes_by_name: HashMap<String, PathBuf>,
    /// Unique resolved toolchain prefixes, in resolution order.
    prefixes: Vec<PathBuf>,
}

impl ResolvedDeps {
    /// Record a resolved dependency toolchain under its formula name,
    /// deduplicating the prefix list (a dep can be both a build and a runtime
    /// dependency).
    fn record(&mut self, dep: &str, toolchain: &Path) {
        self.prefixes_by_name
            .insert(dep.to_string(), toolchain.to_path_buf());
        if !self.prefixes.iter().any(|p| p == toolchain) {
            self.prefixes.push(toolchain.to_path_buf());
        }
    }
}

/// Resolve a formula's build + runtime dependencies into sibling toolchains and build
/// the [`ResolvedDeps`] (its [`BuildEnv`] plus each dep's toolchain prefix),
/// **purely from the formula's data**:
///
/// - Deps macOS itself provides (`uses_from_macos`) are skipped — the Command
///   Line Tools already expose them under `/usr/lib` + `/usr/include`, which the
///   Seatbelt profile grants.
/// - Every other build dependency is **required** (its absence fails the build,
///   routing the formula to brew-emulate) and its `bin` dirs go on `PATH`.
/// - Every other runtime dependency is best-effort (a missing optional library
///   should not abort) and is wired via `-I`/`-L`/`-rpath`/`PKG_CONFIG_PATH`.
///
/// Resolution is **recursive**: [`crate::ensure_macos_toolchain`] re-enters the whole
/// provisioning pipeline for each dep (prebuilt-lang fetch or another source
/// build), so an arbitrarily deep dependency graph is materialized as toolchains.
async fn resolve_dependencies(
    formula: &str,
    spec: &SourceSpec,
    cache_dir: &Path,
    lockfile: Option<&crate::ToolchainLockfile>,
) -> Result<ResolvedDeps> {
    let mut deps = ResolvedDeps::default();

    // A dependency provided by macOS itself needs no toolchain.
    let is_macos_provided = |dep: &str| spec.macos_provided.iter().any(|d| d == dep);

    // Build dependencies — required; their bin dirs go on PATH.
    for dep in &spec.build_dependencies {
        if is_macos_provided(dep) {
            continue;
        }
        let toolchain = Box::pin(crate::ensure_macos_toolchain(dep, cache_dir, lockfile)).await?;
        let manifest = ToolchainManifest::load_or_synthesize(&toolchain).await?;
        deps.env.path_prefix.extend(manifest.path_dirs.clone());
        add_dep_link_flags(&mut deps.env, &toolchain);
        deps.record(dep, &toolchain);
        deps.build_dep_names.push(dep.clone());
        info!(formula, dep, toolchain = %toolchain.display(), "resolved build dependency toolchain");
    }

    // Runtime dependencies — best effort; wire link/include/pkg-config flags so
    // the binary's load commands reference the absolute dependency-toolchain path.
    for dep in &spec.dependencies {
        if is_macos_provided(dep) {
            continue;
        }
        match Box::pin(crate::ensure_macos_toolchain(dep, cache_dir, lockfile)).await {
            Ok(toolchain) => {
                if let Ok(manifest) = ToolchainManifest::load_or_synthesize(&toolchain).await {
                    deps.env.path_prefix.extend(manifest.path_dirs.clone());
                }
                add_dep_link_flags(&mut deps.env, &toolchain);
                deps.record(dep, &toolchain);
                info!(formula, dep, toolchain = %toolchain.display(), "resolved runtime dependency toolchain");
            }
            Err(e) => warn!(
                formula, dep, error = %e,
                "runtime dependency toolchain unavailable; continuing without it"
            ),
        }
    }

    Ok(deps)
}

/// Add `-I`/`-L`/`-rpath`/pkg-config entries for a dependency toolchain so the build
/// links against its absolute path (never `@@HOMEBREW@@`).
fn add_dep_link_flags(env: &mut BuildEnv, toolchain: &Path) {
    let include = toolchain.join("include");
    let lib = toolchain.join("lib");
    if include.is_dir() {
        env.cppflags.push(format!("-I{}", include.display()));
    }
    if lib.is_dir() {
        env.ldflags.push(format!("-L{}", lib.display()));
        env.ldflags.push(format!("-Wl,-rpath,{}", lib.display()));
        let pc = lib.join("pkgconfig");
        if pc.is_dir() {
            env.pkg_config_path.push(pc.display().to_string());
        }
    }
}

/// Download the source tarball and extract it (stripping the top-level dir) into
/// `<scratch>/src`. macOS `tar` (libarchive) auto-detects the compression, so a
/// single `tar xf` handles `.tar.xz` / `.tar.gz` / `.tgz` / `.tar.bz2`.
async fn download_and_extract(formula: &str, spec: &SourceSpec, scratch: &Path) -> Result<PathBuf> {
    let tar_name = spec
        .tarball_url
        .rsplit('/')
        .next()
        .filter(|s| !s.is_empty())
        .unwrap_or("source.tar");
    let tar_path = scratch.join(tar_name);
    info!(url = %spec.tarball_url, "downloading {formula} source tarball");
    // Stream + verify against the formula's `urls.stable.checksum` when present;
    // otherwise the digest is computed (trust-on-first-download) and recorded in
    // the manifest. A mismatch deletes the partial and aborts the build.
    let expected = (!spec.sha256.is_empty()).then_some(spec.sha256.as_str());
    crate::package_index::download_verified(&spec.tarball_url, &tar_path, expected).await?;

    let src_dir = scratch.join("src");
    let _ = tokio::fs::remove_dir_all(&src_dir).await;
    tokio::fs::create_dir_all(&src_dir).await?;
    let untar = tokio::process::Command::new("tar")
        .arg("xf")
        .arg(&tar_path)
        .args(["--strip-components", "1", "-C"])
        .arg(&src_dir)
        .output()
        .await?;
    if !untar.status.success() {
        return Err(ToolchainError::RegistryError {
            message: format!(
                "failed to extract {formula} source: {}",
                String::from_utf8_lossy(&untar.stderr)
            ),
        });
    }
    Ok(src_dir)
}

/// Detect the build system of an extracted source tree, preferring the path that
/// needs the least extra tooling and is canonical for the project shape:
///
/// 1. `bootstrap` (+ `CMakeLists.txt`) → a self-hosting `CMake` (cmake itself).
/// 2. a generated `configure` → autotools (ready to run).
/// 3. a hand-written top-level `Makefile`/`GNUmakefile` → make-prefix (git).
/// 4. `CMakeLists.txt` → `CMake` (built with a `cmake` toolchain).
/// 5. `configure.ac`/`configure.in`/`autogen.sh`/`bootstrap.sh` → autotools
///    (regenerate `configure` first).
///
/// # Errors
///
/// Returns [`ToolchainError::RegistryError`] if no recognised build system is
/// present.
async fn detect_build_system(src_dir: &Path) -> Result<BuildSystem> {
    let exists = |rel: &str| {
        let p = src_dir.join(rel);
        async move { tokio::fs::try_exists(&p).await.unwrap_or(false) }
    };

    let has_bootstrap = exists("bootstrap").await || exists("bootstrap.sh").await;
    let has_cmakelists = exists("CMakeLists.txt").await;

    if has_bootstrap && has_cmakelists {
        // Self-hosting CMake (e.g. cmake's own source): its `bootstrap` builds a
        // minimal cmake then generates the real build — can't use a cmake toolchain to
        // build cmake. The bootstrap wrapper bakes `--prefix` into the build.
        Ok(BuildSystem::CMakeBootstrap)
    } else if exists("configure").await {
        Ok(BuildSystem::Autotools)
    } else if exists("Makefile").await || exists("GNUmakefile").await {
        // A ready top-level Makefile (not Makefile.in) is a hand-written build
        // (git, simple C tools): `make prefix=<toolchain> install`.
        Ok(BuildSystem::MakePrefix)
    } else if has_cmakelists {
        Ok(BuildSystem::CMake)
    } else if exists("configure.ac").await
        || exists("configure.in").await
        || exists("autogen.sh").await
        || has_bootstrap
    {
        // Autotools project shipped without a generated `configure`. Generate it
        // (needs autoconf/automake/libtool on PATH from build-dep toolchains).
        Ok(BuildSystem::Autotools)
    } else {
        Err(ToolchainError::RegistryError {
            message: format!(
                "could not detect a build system \
                 (configure/CMakeLists.txt/Makefile/bootstrap) in {}",
                src_dir.display()
            ),
        })
    }
}

/// Run the detected build system into the toolchain prefix using the host CLT plus the
/// resolved dependency toolchains (no per-formula flags — every quirk is data-driven).
#[allow(clippy::too_many_lines)]
async fn run_build(
    formula: &str,
    src_dir: &Path,
    toolchain: &Path,
    system: BuildSystem,
    build_env: &BuildEnv,
) -> Result<()> {
    let jobs = std::thread::available_parallelism()
        .map_or(4, std::num::NonZero::get)
        .to_string();
    let toolchain_str = toolchain.display().to_string();

    match system {
        BuildSystem::MakePrefix => {
            // Hand-written Makefile: one `make -jN prefix=<toolchain> install`. The
            // Makefile bakes its own install/sysconfdir from `prefix=`.
            let mut cmd = tokio::process::Command::new("make");
            cmd.current_dir(src_dir)
                .arg(format!("-j{jobs}"))
                .arg(format!("prefix={toolchain_str}"))
                .arg("install");
            run_cmd(formula, "make install", &mut cmd, build_env).await?;
        }
        BuildSystem::CMakeBootstrap => {
            // Self-hosting CMake: bootstrap (bakes the install prefix), then make.
            run_cmd(
                formula,
                "bootstrap",
                tokio::process::Command::new("./bootstrap")
                    .current_dir(src_dir)
                    .arg(format!("--prefix={toolchain_str}"))
                    .arg(format!("--parallel={jobs}")),
                build_env,
            )
            .await?;
            run_cmd(
                formula,
                "make",
                tokio::process::Command::new("make")
                    .current_dir(src_dir)
                    .arg(format!("-j{jobs}")),
                build_env,
            )
            .await?;
            run_cmd(
                formula,
                "make install",
                tokio::process::Command::new("make")
                    .current_dir(src_dir)
                    .arg("install"),
                build_env,
            )
            .await?;
        }
        BuildSystem::Autotools => {
            // Generate `configure` if the tarball shipped only configure.ac.
            if !src_dir.join("configure").is_file() {
                let autogen = src_dir.join("autogen.sh");
                if autogen.is_file() {
                    run_cmd(
                        formula,
                        "autogen.sh",
                        tokio::process::Command::new("sh")
                            .current_dir(src_dir)
                            .arg("autogen.sh"),
                        build_env,
                    )
                    .await?;
                } else {
                    run_cmd(
                        formula,
                        "autoreconf",
                        tokio::process::Command::new("autoreconf")
                            .current_dir(src_dir)
                            .arg("-fi"),
                        build_env,
                    )
                    .await?;
                }
            }

            let mut configure = tokio::process::Command::new("./configure");
            configure
                .current_dir(src_dir)
                .arg(format!("--prefix={toolchain_str}"));
            run_cmd(formula, "configure", &mut configure, build_env).await?;

            let mut make = tokio::process::Command::new("make");
            make.current_dir(src_dir).arg(format!("-j{jobs}"));
            run_cmd(formula, "make", &mut make, build_env).await?;

            run_cmd(
                formula,
                "make install",
                tokio::process::Command::new("make")
                    .current_dir(src_dir)
                    .arg("install"),
                build_env,
            )
            .await?;
        }
        BuildSystem::CMake => {
            let build_dir = src_dir.join("_zl_build");
            let mut configure = tokio::process::Command::new("cmake");
            configure
                .current_dir(src_dir)
                .arg("-S")
                .arg(".")
                .arg("-B")
                .arg(&build_dir)
                .arg(format!("-DCMAKE_INSTALL_PREFIX={toolchain_str}"))
                .arg("-DCMAKE_BUILD_TYPE=Release");
            run_cmd(formula, "cmake configure", &mut configure, build_env).await?;

            run_cmd(
                formula,
                "cmake build",
                tokio::process::Command::new("cmake")
                    .current_dir(src_dir)
                    .arg("--build")
                    .arg(&build_dir)
                    .arg("-j")
                    .arg(&jobs),
                build_env,
            )
            .await?;

            run_cmd(
                formula,
                "cmake install",
                tokio::process::Command::new("cmake")
                    .current_dir(src_dir)
                    .arg("--install")
                    .arg(&build_dir),
                build_env,
            )
            .await?;
        }
    }
    Ok(())
}

/// Apply the [`BuildEnv`] to a command and run it, returning a build error with
/// the tail of stderr on failure. The host environment is inherited; `PATH`,
/// `CPPFLAGS`, `LDFLAGS` and `PKG_CONFIG_PATH` are prepended/augmented.
async fn run_cmd(
    formula: &str,
    step: &str,
    cmd: &mut tokio::process::Command,
    env: &BuildEnv,
) -> Result<()> {
    // PATH: dependency toolchain bins first, then the host CLT/system paths.
    let host_path = std::env::var("PATH").unwrap_or_default();
    let system_path = "/usr/bin:/bin:/usr/sbin:/sbin";
    let mut path_parts: Vec<String> = env.path_prefix.clone();
    if !host_path.is_empty() {
        path_parts.push(host_path);
    }
    path_parts.push(system_path.to_string());
    cmd.env("PATH", path_parts.join(":"));

    if !env.cppflags.is_empty() {
        cmd.env("CPPFLAGS", env.cppflags.join(" "));
    }
    if !env.ldflags.is_empty() {
        cmd.env("LDFLAGS", env.ldflags.join(" "));
    }
    if !env.pkg_config_path.is_empty() {
        cmd.env("PKG_CONFIG_PATH", env.pkg_config_path.join(":"));
    }

    info!(formula, step, "running source build step");
    let out = cmd.output().await?;
    if !out.status.success() {
        let tail = String::from_utf8_lossy(&out.stderr)
            .lines()
            .rev()
            .take(25)
            .collect::<Vec<_>>()
            .into_iter()
            .rev()
            .collect::<Vec<_>>()
            .join("\n");
        return Err(ToolchainError::RegistryError {
            message: format!("{formula} `{step}` failed:\n{tail}"),
        });
    }
    Ok(())
}

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

    #[tokio::test]
    async fn detect_autotools_from_configure() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("configure"), b"#!/bin/sh\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::Autotools
        );
    }

    #[tokio::test]
    async fn detect_cmake_from_cmakelists() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("CMakeLists.txt"), b"project(x)\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::CMake
        );
    }

    #[tokio::test]
    async fn detect_make_from_bare_makefile() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("Makefile"), b"all:\n\ttrue\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::MakePrefix
        );
    }

    /// A self-hosting `CMake` (cmake itself ships `bootstrap` + `CMakeLists.txt`)
    /// must bootstrap, NOT try to build with a cmake we don't yet have.
    #[tokio::test]
    async fn detect_cmake_bootstrap_for_self_host() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("bootstrap"), b"#!/bin/sh\n")
            .await
            .unwrap();
        tokio::fs::write(tmp.path().join("CMakeLists.txt"), b"project(cmake)\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::CMakeBootstrap
        );
    }

    /// A generated `configure` wins over a sibling `Makefile.in`; and a tree with
    /// only `configure.ac` is still autotools (regenerated first).
    #[tokio::test]
    async fn detect_autotools_from_configure_ac_only() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("configure.ac"), b"AC_INIT([x],[1])\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::Autotools
        );
    }

    /// A hand-written `Makefile` that also ships `configure.ac` (git's shape:
    /// no generated `configure`) takes the ready Makefile path, not the
    /// regenerate-with-autotools path.
    #[tokio::test]
    async fn detect_prefers_ready_makefile_over_configure_ac() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("Makefile"), b"all:\n\ttrue\n")
            .await
            .unwrap();
        tokio::fs::write(tmp.path().join("configure.ac"), b"AC_INIT([git],[1])\n")
            .await
            .unwrap();
        assert_eq!(
            detect_build_system(tmp.path()).await.unwrap(),
            BuildSystem::MakePrefix
        );
    }

    #[tokio::test]
    async fn detect_fails_on_unknown_tree() {
        let tmp = tempfile::tempdir().unwrap();
        tokio::fs::write(tmp.path().join("README"), b"hi\n")
            .await
            .unwrap();
        assert!(detect_build_system(tmp.path()).await.is_err());
    }

    #[test]
    fn dep_link_flags_use_absolute_toolchain_paths() {
        let tmp = tempfile::tempdir().unwrap();
        let toolchain = tmp.path();
        std::fs::create_dir_all(toolchain.join("include")).unwrap();
        std::fs::create_dir_all(toolchain.join("lib/pkgconfig")).unwrap();
        let mut env = BuildEnv::default();
        add_dep_link_flags(&mut env, toolchain);
        assert!(env.cppflags.iter().any(|f| f.contains("/include")));
        assert!(env.ldflags.iter().any(|f| f.starts_with("-L")));
        assert!(env
            .ldflags
            .iter()
            .any(|f| f.contains("-Wl,-rpath,") && !f.contains("@@HOMEBREW")));
        assert!(env.pkg_config_path.iter().any(|p| p.contains("pkgconfig")));
    }

    /// `resolve_dependencies` skips `uses_from_macos` deps without touching the
    /// network: a spec whose every dep is macOS-provided resolves to an empty
    /// build env and no resolved build deps.
    #[tokio::test]
    async fn macos_provided_deps_are_skipped_offline() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = SourceSpec {
            version: "1.0".to_string(),
            tarball_url: "https://example/x.tar.gz".to_string(),
            sha256: String::new(),
            dependencies: vec!["curl".to_string(), "zlib".to_string()],
            build_dependencies: vec!["expat".to_string()],
            macos_provided: vec!["curl".to_string(), "zlib".to_string(), "expat".to_string()],
        };
        let deps = resolve_dependencies("demo", &spec, tmp.path(), None)
            .await
            .expect("all-macos-provided deps resolve offline");
        assert!(
            deps.build_dep_names.is_empty(),
            "no toolchain deps to resolve"
        );
        assert!(deps.prefixes_by_name.is_empty());
        assert!(deps.prefixes.is_empty());
        assert!(deps.env.path_prefix.is_empty());
        assert!(deps.env.cppflags.is_empty());
        assert!(deps.env.ldflags.is_empty());
        assert!(deps.env.pkg_config_path.is_empty());
    }

    /// The manifest's env is derived from the installed LAYOUT, not the formula
    /// name: a toolchain with `libexec/git-core` gets `GIT_EXEC_PATH`; one without
    /// gets none — for the same formula name either way.
    #[tokio::test]
    async fn manifest_env_is_layout_derived_not_name_derived() {
        let spec = SourceSpec {
            version: "2.55.0".to_string(),
            tarball_url: "https://example/git.tar.xz".to_string(),
            sha256: String::new(),
            dependencies: vec![],
            build_dependencies: vec![],
            macos_provided: vec![],
        };

        // Toolchain WITH the git-core exec dir → GIT_EXEC_PATH present.
        let with_dir = tempfile::tempdir().unwrap();
        tokio::fs::create_dir_all(with_dir.path().join("libexec/git-core"))
            .await
            .unwrap();
        let m = build_manifest("git", &spec, with_dir.path(), vec![]).await;
        assert_eq!(
            m.env.get("GIT_EXEC_PATH"),
            Some(
                &with_dir
                    .path()
                    .join("libexec/git-core")
                    .display()
                    .to_string()
            )
        );

        // Same formula NAME, no git-core dir → no GIT_EXEC_PATH (layout-driven).
        let without_dir = tempfile::tempdir().unwrap();
        let m2 = build_manifest("git", &spec, without_dir.path(), vec![]).await;
        assert!(!m2.env.contains_key("GIT_EXEC_PATH"));
    }

    // -----------------------------------------------------------------------
    // Container-recipe route (C3). These tests exercise the pure/observable
    // pieces (env assembly, pre-fetch layout, request assembly, finalize) and
    // pass a LOCAL mock executor directly — they never touch the process-global
    // executor slot, which belongs exclusively to `executor.rs`'s single
    // sequential test. The end-to-end route (real recipe fetch + container
    // run) is deferred to D5's live `#[ignore]` tier.
    // -----------------------------------------------------------------------

    /// A minimal plan with the given env pairs and deparallelize flag.
    fn plan_with(env: &[(&str, &str)], deparallelize: bool) -> InstallPlan {
        InstallPlan {
            steps: vec![],
            resources: vec![],
            patches: vec![],
            env: env
                .iter()
                .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
                .collect(),
            deparallelize,
        }
    }

    #[test]
    fn plan_env_merges_env_and_deparallelize_forces_serial_make() {
        // The plan's accumulated ENV is carried through verbatim; no
        // deparallelize → no MAKEFLAGS injected.
        let env = plan_env(&plan_with(&[("CFLAGS", "-O2"), ("LANG", "C")], false));
        assert_eq!(env.get("CFLAGS").map(String::as_str), Some("-O2"));
        assert_eq!(env.get("LANG").map(String::as_str), Some("C"));
        assert!(!env.contains_key("MAKEFLAGS"));

        // ENV.deparallelize → MAKEFLAGS=-j1, overriding a recipe-set value.
        let env = plan_env(&plan_with(&[("MAKEFLAGS", "-j8"), ("CFLAGS", "-O2")], true));
        assert_eq!(env.get("MAKEFLAGS").map(String::as_str), Some("-j1"));
        assert_eq!(env.get("CFLAGS").map(String::as_str), Some("-O2"));
    }

    /// Pre-fetch destinations: `<resources>/<name>/<url-basename>` for
    /// resources (with a stable fallback name for basename-less URLs) and
    /// `<resources>/patches/<index>` for patches — and the layout is writable
    /// exactly as assembled (no network involved).
    #[test]
    fn prefetch_destination_layout_is_per_resource_and_patch_index() {
        let tmp = tempfile::tempdir().unwrap();
        let resources_dir = tmp.path().join("resources");

        let res = ResourceSpec {
            name: "certifi".to_string(),
            url: "https://files.example/certifi-2026.1.tar.gz".to_string(),
            sha256: "ab".repeat(32),
            stage_to: None,
        };
        let dest = resource_dest(&resources_dir, &res);
        assert_eq!(
            dest,
            resources_dir.join("certifi").join("certifi-2026.1.tar.gz")
        );

        // A URL with an empty basename falls back to a stable name.
        let odd = ResourceSpec {
            name: "odd".to_string(),
            url: "https://files.example/".to_string(),
            sha256: "cd".repeat(32),
            stage_to: None,
        };
        assert_eq!(
            resource_dest(&resources_dir, &odd),
            resources_dir.join("odd").join("resource.tar")
        );

        let patch0 = patch_dest(&resources_dir, 0);
        assert_eq!(patch0, resources_dir.join("patches").join("0"));
        assert_eq!(
            patch_dest(&resources_dir, 7),
            resources_dir.join("patches").join("7")
        );

        // Fake write proves the assembled layout is directly materializable
        // (download_verified creates parents the same way).
        std::fs::create_dir_all(dest.parent().unwrap()).unwrap();
        std::fs::write(&dest, b"fake resource bytes").unwrap();
        std::fs::create_dir_all(patch0.parent().unwrap()).unwrap();
        std::fs::write(&patch0, b"--- a\n+++ b\n").unwrap();
        assert!(dest.is_file());
        assert!(patch0.is_file());
    }

    /// `prefetch_plan_inputs` needs no network for the decisions under test:
    /// an input-less plan short-circuits to `None`, and an empty/blank sha256
    /// is rejected BEFORE any download is attempted (the choco weak-checksum
    /// case never reaches this macOS path).
    #[tokio::test]
    async fn prefetch_short_circuits_empty_plan_and_rejects_missing_sha_offline() {
        let tmp = tempfile::tempdir().unwrap();

        let none = prefetch_plan_inputs("demo", &plan_with(&[], false), tmp.path())
            .await
            .expect("no resources/patches → nothing to stage");
        assert!(none.is_none());

        let mut plan = plan_with(&[], false);
        plan.resources.push(ResourceSpec {
            name: "noverify".to_string(),
            url: "https://files.example/x.tar.gz".to_string(),
            sha256: String::new(),
            stage_to: None,
        });
        let err = prefetch_plan_inputs("demo", &plan, tmp.path())
            .await
            .expect_err("an empty resource sha256 must be an error on the macOS path");
        assert!(err.to_string().contains("noverify"));

        let mut plan = plan_with(&[], false);
        plan.patches.push(crate::recipe::PatchSpec {
            url: "https://files.example/fix.patch".to_string(),
            sha256: "  ".to_string(),
            strip: 1,
        });
        assert!(
            prefetch_plan_inputs("demo", &plan, tmp.path())
                .await
                .is_err(),
            "a blank patch sha256 must be an error too"
        );
    }

    /// The assembled request denies the network, targets macOS, carries the
    /// deduped dep prefixes + their bin dirs as PATH prefix (mirroring
    /// `run_cmd`), and merges the plan env (+ MAKEFLAGS on deparallelize).
    #[test]
    fn container_request_denies_network_and_wires_deps_and_env() {
        let tmp = tempfile::tempdir().unwrap();
        let toolchain = tmp.path().join("jq-1.8.1-arm64");
        let scratch = toolchain.join(".build");
        let dep_prefix = tmp.path().join("oniguruma-6.9.10-arm64");

        let mut deps = ResolvedDeps::default();
        deps.env
            .path_prefix
            .push(dep_prefix.join("bin").display().to_string());
        deps.record("oniguruma", &dep_prefix);
        deps.record("oniguruma", &dep_prefix); // build+runtime double-record dedupes

        let req = assemble_container_request(
            "jq",
            &toolchain,
            &scratch,
            plan_with(&[("CFLAGS", "-O2")], true),
            &deps,
            scratch.join("src"),
            Some(scratch.join("resources")),
        );

        assert_eq!(req.tool, "jq");
        assert_eq!(req.platform, crate::ToolPlatform::MacOS);
        assert_eq!(
            req.net,
            NetPolicy::Deny,
            "container recipe builds must run with the network denied"
        );
        assert_eq!(req.prefix, toolchain);
        assert_eq!(req.scratch_dir, scratch);
        assert_eq!(req.src_dir, scratch.join("src"));
        assert_eq!(req.resources_dir, Some(scratch.join("resources")));
        assert_eq!(
            req.dep_toolchains,
            vec![dep_prefix.clone()],
            "dep prefixes deduped, in resolution order"
        );
        assert_eq!(
            req.path_prefix,
            vec![dep_prefix.join("bin").display().to_string()]
        );
        assert_eq!(req.env.get("CFLAGS").map(String::as_str), Some("-O2"));
        assert_eq!(req.env.get("MAKEFLAGS").map(String::as_str), Some("-j1"));
    }

    /// Local mock executor passed DIRECTLY as `&dyn` (never through the
    /// process-global slot — that slot belongs to `executor.rs`'s single
    /// sequential test). Captures the request it served; optionally fails.
    struct CapturingExecutor {
        seen: std::sync::Mutex<Option<ContainerBuildRequest>>,
        fail: bool,
    }

    impl ContainerBuildExecutor for CapturingExecutor {
        fn execute<'a>(
            &'a self,
            req: &'a ContainerBuildRequest,
        ) -> std::pin::Pin<
            Box<
                dyn std::future::Future<Output = Result<crate::executor::ContainerBuildReport>>
                    + Send
                    + 'a,
            >,
        > {
            Box::pin(async move {
                *self.seen.lock().unwrap() = Some(req.clone());
                if self.fail {
                    Err(ToolchainError::RegistryError {
                        message: "mock container build failed".to_string(),
                    })
                } else {
                    Ok(crate::executor::ContainerBuildReport {
                        log_tail: String::new(),
                    })
                }
            })
        }
    }

    /// A successful container run finishes the toolchain EXACTLY like the
    /// generic build: manifest written (same fields, `SourceBuild` variant),
    /// scratch removed, `.ready` stamped LAST. A failed run propagates the
    /// error and leaves NO `.ready`, so the caller's fall-through to the
    /// generic build starts clean.
    #[tokio::test]
    async fn container_run_finalizes_like_generic_build_and_failure_leaves_no_ready() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = SourceSpec {
            version: "1.8.1".to_string(),
            tarball_url: "https://example/jq-1.8.1.tar.gz".to_string(),
            sha256: "cafe".to_string(),
            dependencies: vec![],
            build_dependencies: vec![],
            macos_provided: vec![],
        };

        // Success path.
        let toolchain = tmp.path().join("jq-1.8.1-arm64");
        let scratch = toolchain.join(".build");
        tokio::fs::create_dir_all(scratch.join("src"))
            .await
            .unwrap();
        let req = assemble_container_request(
            "jq",
            &toolchain,
            &scratch,
            plan_with(&[], false),
            &ResolvedDeps::default(),
            scratch.join("src"),
            None,
        );
        let exec = CapturingExecutor {
            seen: std::sync::Mutex::new(None),
            fail: false,
        };
        run_request_and_finalize(&spec, vec!["pkgconf".to_string()], req, &exec)
            .await
            .expect("mock container build should finalize the toolchain");

        let seen = exec
            .seen
            .lock()
            .unwrap()
            .take()
            .expect("executor must have been invoked with the assembled request");
        assert_eq!(seen.tool, "jq");
        assert_eq!(seen.net, NetPolicy::Deny);

        let manifest = ToolchainManifest::read_from_toolchain(&toolchain)
            .await
            .unwrap()
            .expect("manifest written before .ready");
        assert_eq!(manifest.tool, "jq");
        assert_eq!(manifest.version, "1.8.1");
        assert_eq!(manifest.platform, "macos");
        assert_eq!(manifest.build_deps, vec!["pkgconf"]);
        assert_eq!(
            manifest.source,
            ToolchainSource::SourceBuild {
                url: spec.tarball_url.clone(),
                sha256: spec.sha256.clone(),
            }
        );
        assert!(toolchain.join(".ready").is_file(), ".ready stamped last");
        assert!(!scratch.exists(), "scratch cleaned like the generic build");

        // Failure path: error propagates, NO .ready stamped.
        let toolchain2 = tmp.path().join("jq-9.9.9-arm64");
        let scratch2 = toolchain2.join(".build");
        tokio::fs::create_dir_all(&scratch2).await.unwrap();
        let req2 = assemble_container_request(
            "jq",
            &toolchain2,
            &scratch2,
            plan_with(&[], false),
            &ResolvedDeps::default(),
            scratch2.join("src"),
            None,
        );
        let failing = CapturingExecutor {
            seen: std::sync::Mutex::new(None),
            fail: true,
        };
        let err = run_request_and_finalize(&spec, vec![], req2, &failing)
            .await
            .expect_err("executor failure must propagate");
        assert!(err.to_string().contains("mock container build failed"));
        assert!(
            !toolchain2.join(".ready").exists(),
            "no .ready on failure — the fall-through must not see a ready toolchain"
        );
    }
}