falsegreen_agent/

runtime.rs

//! Pinned llama.cpp runtime catalog and integrity-preserving installation.

use std::fs::{self, File, OpenOptions};
use std::io::Write;
use std::path::{Component, Path, PathBuf};
use std::thread;
use std::time::{Duration, Instant};

use flate2::read::GzDecoder;
use fs2::FileExt;
use serde::{Deserialize, Serialize};
use thiserror::Error;
use uuid::Uuid;

use crate::artifact::{ArtifactError, ArtifactFetcher, ArtifactSpec, hash_file};
use crate::hardware::{
    Architecture, HardwareProfile, OperatingSystem, RuntimeBackend, RuntimePlatform,
};

/// Official llama.cpp nightly built from the source commit recorded by the NeoHorse qualification.
pub const LLAMA_CPP_RELEASE: &str = "b10630";
pub const LLAMA_CPP_COMMIT: &str = "d222767c7a6516559a3f49e7721b6c6b1acc87b4";
pub const LLAMA_CPP_VERSION: &str = "0.3.0-dev";

const MANIFEST_FILE: &str = ".falsegreen-runtime-manifest.json";
const MAX_EXTRACTED_BYTES: u64 = 4 * 1024 * 1024 * 1024;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
enum ArchiveFormat {
    TarGz,
    Zip,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct RuntimeArtifact {
    spec: ArtifactSpec,
    platform: RuntimePlatform,
    backend: RuntimeBackend,
    archive_format: ArchiveFormat,
    server_relative_path: PathBuf,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RuntimeInstall {
    pub root: PathBuf,
    pub server_executable: PathBuf,
    pub artifact_file_name: String,
    pub artifact_sha256: String,
    pub platform: RuntimePlatform,
    pub backend: RuntimeBackend,
    pub release: String,
    pub commit: String,
    pub reused: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuntimeCacheInspection {
    pub archive_path: PathBuf,
    pub install_root: PathBuf,
    pub server_executable: PathBuf,
    pub artifact_file_name: String,
    pub artifact_sha256: String,
    pub artifact_size_bytes: u64,
    pub archive_present: bool,
    pub archive_digest_verified: Option<bool>,
    pub install_present: bool,
    pub install_verified: bool,
}

#[derive(Debug, Clone)]
pub struct LlamaRuntimeManager {
    cache_root: PathBuf,
    fetcher: ArtifactFetcher,
    lock_timeout: Duration,
}

impl LlamaRuntimeManager {
    #[must_use]
    pub fn new(cache_root: impl Into<PathBuf>, fetcher: ArtifactFetcher) -> Self {
        Self {
            cache_root: cache_root.into(),
            fetcher,
            lock_timeout: Duration::from_secs(60),
        }
    }

    #[must_use]
    pub const fn with_lock_timeout(mut self, timeout: Duration) -> Self {
        self.lock_timeout = timeout;
        self
    }

    pub fn ensure(
        &self,
        hardware: &HardwareProfile,
        preferred_backend: Option<RuntimeBackend>,
    ) -> Result<RuntimeInstall, RuntimeError> {
        self.ensure_for(
            hardware.platform,
            preferred_backend.unwrap_or_else(|| hardware.recommended_backend()),
        )
    }

    pub fn ensure_for(
        &self,
        platform: RuntimePlatform,
        backend: RuntimeBackend,
    ) -> Result<RuntimeInstall, RuntimeError> {
        let artifact = runtime_artifact(platform, backend)?;
        let archive_path = self
            .cache_root
            .join("downloads")
            .join("llama.cpp")
            .join(LLAMA_CPP_RELEASE)
            .join(&artifact.spec.file_name);
        self.fetcher.ensure_file(&artifact.spec, &archive_path)?;

        let install_parent = self
            .cache_root
            .join("runtimes")
            .join("llama.cpp")
            .join(LLAMA_CPP_RELEASE);
        fs::create_dir_all(&install_parent)
            .map_err(|source| io_error("create runtime cache", &install_parent, source))?;
        let install_name = format!("{}-{}", platform.cache_key(), backend.cache_key());
        let install_root = install_parent.join(install_name);
        let lock_path = install_root.with_extension("lock");
        let _lock = DirectoryLock::acquire(&lock_path, self.lock_timeout)?;

        if install_root.exists() {
            match validate_install(&install_root, &artifact) {
                Ok(server_executable) => {
                    return Ok(RuntimeInstall {
                        root: install_root,
                        server_executable,
                        artifact_file_name: artifact.spec.file_name.clone(),
                        artifact_sha256: artifact.spec.sha256.clone(),
                        platform,
                        backend,
                        release: LLAMA_CPP_RELEASE.to_owned(),
                        commit: LLAMA_CPP_COMMIT.to_owned(),
                        reused: true,
                    });
                }
                Err(RuntimeError::InvalidInstall(_)) => quarantine_directory(&install_root)?,
                Err(error) => return Err(error),
            }
        }

        let staging = install_parent.join(format!(".staging-{}", Uuid::new_v4()));
        let mut staging_guard = StagingDirectory::create(staging)?;
        extract_archive(&archive_path, staging_guard.path(), artifact.archive_format)?;
        let server_executable = staging_guard.path().join(&artifact.server_relative_path);
        if !server_executable.is_file() {
            return Err(RuntimeError::InvalidInstall(format!(
                "archive did not contain expected server executable {}",
                artifact.server_relative_path.display()
            )));
        }
        make_executable(&server_executable)?;
        let entries = collect_entries(staging_guard.path())?;
        let manifest = InstallManifest {
            schema_version: 1,
            release: LLAMA_CPP_RELEASE.to_owned(),
            commit: LLAMA_CPP_COMMIT.to_owned(),
            platform,
            backend,
            archive_sha256: artifact.spec.sha256.to_ascii_lowercase(),
            server_relative_path: artifact.server_relative_path.clone(),
            entries,
        };
        write_manifest(staging_guard.path(), &manifest)?;
        staging_guard.publish(&install_root)?;
        let server_executable = install_root.join(&artifact.server_relative_path);
        validate_install(&install_root, &artifact)?;

        Ok(RuntimeInstall {
            root: install_root,
            server_executable,
            artifact_file_name: artifact.spec.file_name,
            artifact_sha256: artifact.spec.sha256,
            platform,
            backend,
            release: LLAMA_CPP_RELEASE.to_owned(),
            commit: LLAMA_CPP_COMMIT.to_owned(),
            reused: false,
        })
    }

    /// Inspect pinned runtime cache paths without creating, quarantining, or downloading data.
    pub fn inspect_for(
        &self,
        platform: RuntimePlatform,
        backend: RuntimeBackend,
        verify_archive_digest: bool,
    ) -> Result<RuntimeCacheInspection, RuntimeError> {
        let artifact = runtime_artifact(platform, backend)?;
        let archive_path = self
            .cache_root
            .join("downloads")
            .join("llama.cpp")
            .join(LLAMA_CPP_RELEASE)
            .join(&artifact.spec.file_name);
        let install_root = self
            .cache_root
            .join("runtimes")
            .join("llama.cpp")
            .join(LLAMA_CPP_RELEASE)
            .join(format!("{}-{}", platform.cache_key(), backend.cache_key()));
        let archive_present = fs::symlink_metadata(&archive_path)
            .is_ok_and(|metadata| metadata.file_type().is_file());
        let archive_digest_verified = (archive_present && verify_archive_digest)
            .then(|| crate::artifact::verify_file(&archive_path, &artifact.spec).is_ok());
        let install_present =
            fs::symlink_metadata(&install_root).is_ok_and(|metadata| metadata.file_type().is_dir());
        let validated_server = install_present
            .then(|| validate_install(&install_root, &artifact))
            .transpose();
        let (server_executable, install_verified) = match validated_server {
            Ok(Some(path)) => (path, true),
            Ok(None) | Err(_) => (install_root.join(&artifact.server_relative_path), false),
        };
        Ok(RuntimeCacheInspection {
            archive_path,
            install_root,
            server_executable,
            artifact_file_name: artifact.spec.file_name,
            artifact_sha256: artifact.spec.sha256,
            artifact_size_bytes: artifact.spec.size_bytes,
            archive_present,
            archive_digest_verified,
            install_present,
            install_verified,
        })
    }
}

#[derive(Debug, Error)]
pub enum RuntimeError {
    #[error(transparent)]
    Artifact(#[from] ArtifactError),
    #[error("no pinned llama-server artifact for {platform} with {backend:?} backend")]
    UnsupportedTarget {
        platform: RuntimePlatform,
        backend: RuntimeBackend,
    },
    #[error("runtime archive contains an unsafe or unsupported entry: {0}")]
    UnsafeArchive(String),
    #[error("managed runtime installation is not trustworthy: {0}")]
    InvalidInstall(String),
    #[error("timed out waiting for runtime install lock {path} after {seconds} seconds")]
    LockTimeout { path: PathBuf, seconds: u64 },
    #[error("could not {operation} at {path}: {source}")]
    Io {
        operation: &'static str,
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },
    #[error("could not decode runtime archive: {0}")]
    Archive(String),
    #[error("could not serialize runtime manifest: {0}")]
    Manifest(#[from] serde_json::Error),
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct InstallManifest {
    schema_version: u32,
    release: String,
    commit: String,
    platform: RuntimePlatform,
    backend: RuntimeBackend,
    archive_sha256: String,
    server_relative_path: PathBuf,
    entries: Vec<InstalledEntry>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
enum InstalledEntry {
    File {
        path: PathBuf,
        sha256: String,
        size_bytes: u64,
    },
    Symlink {
        path: PathBuf,
        target: PathBuf,
    },
}

fn runtime_artifact(
    platform: RuntimePlatform,
    backend: RuntimeBackend,
) -> Result<RuntimeArtifact, RuntimeError> {
    let (name, digest, size, format) = match (platform.os, platform.architecture, backend) {
        (OperatingSystem::Linux, Architecture::X86_64, RuntimeBackend::Cpu) => (
            "llama-b10630-bin-ubuntu-x64.tar.gz",
            "ab5e2c472ae317a8e2210272a25569a74c054a05e196feef200bfef270d2204b",
            16_292_161,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Linux, Architecture::X86_64, RuntimeBackend::Rocm) => (
            "llama-b10630-bin-ubuntu-rocm-7.14-x64.tar.gz",
            "a44a8649b44398465ad49bccd1eda39e7019caade63f918c220e05e3572aaaee",
            213_952_218,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Linux, Architecture::X86_64, RuntimeBackend::Vulkan) => (
            "llama-b10630-bin-ubuntu-vulkan-x64.tar.gz",
            "d2d3da1bab8c3b85dfd130a8bcbec9ca83abc584000ee688d92c296550666353",
            32_914_728,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Linux, Architecture::Aarch64, RuntimeBackend::Cpu) => (
            "llama-b10630-bin-ubuntu-arm64.tar.gz",
            "783bd5dd828cdb9a26a26b85ce9adc2951f2be0c37e0b9593059116431a8e771",
            13_042_152,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Linux, Architecture::Aarch64, RuntimeBackend::Vulkan) => (
            "llama-b10630-bin-ubuntu-vulkan-arm64.tar.gz",
            "6dee633ff7f9f5e2279eeda15bd464b5b3894af5bd602b3a2d7c7da27cae7e57",
            26_779_926,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Macos, Architecture::X86_64, RuntimeBackend::Metal) => (
            "llama-b10630-bin-macos-x64.tar.gz",
            "49100754ff4211e6c0e558fe3e9384d59eca51ce1c70673a632f788c6b58d800",
            11_034_413,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Macos, Architecture::Aarch64, RuntimeBackend::Metal) => (
            "llama-b10630-bin-macos-arm64.tar.gz",
            "3394752534fc7cb62bf861868b750a704ead264ac9fac7083e7d49e835a19a10",
            10_963_541,
            ArchiveFormat::TarGz,
        ),
        (OperatingSystem::Windows, Architecture::X86_64, RuntimeBackend::Cpu) => (
            "llama-b10630-bin-win-cpu-x64.zip",
            "45fe4ffb81386872ee3cbb1ed83473df1ed3ce68edcb3d2d0bd31c5a16c4f416",
            18_067_881,
            ArchiveFormat::Zip,
        ),
        (OperatingSystem::Windows, Architecture::X86_64, RuntimeBackend::Rocm) => (
            "llama-b10630-bin-win-rocm-7.14-x64.zip",
            "fb067cc91e8a09885d3dbb9dc9ebc67279c1e11a078a0ebf8aa05c4cc8b6b0bb",
            196_227_720,
            ArchiveFormat::Zip,
        ),
        (OperatingSystem::Windows, Architecture::X86_64, RuntimeBackend::Vulkan) => (
            "llama-b10630-bin-win-vulkan-x64.zip",
            "09e9afa74194522465110df724250dae40393f66b42a8ce8901c4dab6ed17c1f",
            34_403_736,
            ArchiveFormat::Zip,
        ),
        (OperatingSystem::Windows, Architecture::Aarch64, RuntimeBackend::Cpu) => (
            "llama-b10630-bin-win-cpu-arm64.zip",
            "c7e0e822fc3cc967e4111b6ab0685ffa11ee2f62923b6c35527e601f8c9e6da4",
            11_846_985,
            ArchiveFormat::Zip,
        ),
        _ => return Err(RuntimeError::UnsupportedTarget { platform, backend }),
    };
    let server_relative_path = if platform.os == OperatingSystem::Windows {
        PathBuf::from("llama-server.exe")
    } else {
        PathBuf::from(format!("llama-{LLAMA_CPP_RELEASE}/llama-server"))
    };
    Ok(RuntimeArtifact {
        spec: ArtifactSpec {
            id: "llama.cpp".to_owned(),
            version: LLAMA_CPP_RELEASE.to_owned(),
            file_name: name.to_owned(),
            url: format!(
                "https://github.com/ggml-org/llama.cpp/releases/download/{LLAMA_CPP_RELEASE}/{name}"
            ),
            sha256: digest.to_owned(),
            size_bytes: size,
        },
        platform,
        backend,
        archive_format: format,
        server_relative_path,
    })
}

fn extract_archive(
    archive_path: &Path,
    destination: &Path,
    format: ArchiveFormat,
) -> Result<(), RuntimeError> {
    match format {
        ArchiveFormat::TarGz => extract_tar_gz(archive_path, destination),
        ArchiveFormat::Zip => extract_zip(archive_path, destination),
    }
}

fn extract_tar_gz(archive_path: &Path, destination: &Path) -> Result<(), RuntimeError> {
    let file = File::open(archive_path)
        .map_err(|source| io_error("open runtime archive", archive_path, source))?;
    let mut archive = tar::Archive::new(GzDecoder::new(file));
    let entries = archive
        .entries()
        .map_err(|error| RuntimeError::Archive(error.to_string()))?;
    let mut extracted = 0_u64;
    for entry in entries {
        let mut entry = entry.map_err(|error| RuntimeError::Archive(error.to_string()))?;
        let relative = entry
            .path()
            .map_err(|error| RuntimeError::Archive(error.to_string()))?
            .into_owned();
        validate_relative_path(&relative)?;
        let kind = entry.header().entry_type();
        if kind.is_file() {
            extracted = bounded_add(extracted, entry.size(), &relative)?;
        } else if kind.is_symlink() {
            let target = entry
                .link_name()
                .map_err(|error| RuntimeError::Archive(error.to_string()))?
                .ok_or_else(|| {
                    RuntimeError::UnsafeArchive(format!(
                        "symlink {} has no target",
                        relative.display()
                    ))
                })?;
            validate_symlink_target(&relative, &target)?;
        } else if !kind.is_dir() {
            return Err(RuntimeError::UnsafeArchive(format!(
                "{} has unsupported tar entry type",
                relative.display()
            )));
        }
        let unpacked = entry
            .unpack_in(destination)
            .map_err(|error| RuntimeError::Archive(error.to_string()))?;
        if !unpacked {
            return Err(RuntimeError::UnsafeArchive(relative.display().to_string()));
        }
    }
    Ok(())
}

fn extract_zip(archive_path: &Path, destination: &Path) -> Result<(), RuntimeError> {
    let file = File::open(archive_path)
        .map_err(|source| io_error("open runtime archive", archive_path, source))?;
    let mut archive =
        zip::ZipArchive::new(file).map_err(|error| RuntimeError::Archive(error.to_string()))?;
    let mut extracted = 0_u64;
    for index in 0..archive.len() {
        let mut entry = archive
            .by_index(index)
            .map_err(|error| RuntimeError::Archive(error.to_string()))?;
        let relative = entry.enclosed_name().ok_or_else(|| {
            RuntimeError::UnsafeArchive(format!("unsafe zip path {}", entry.name()))
        })?;
        validate_relative_path(&relative)?;
        if entry
            .unix_mode()
            .is_some_and(|mode| mode & 0o170_000 == 0o120_000)
        {
            return Err(RuntimeError::UnsafeArchive(format!(
                "zip symlinks are not accepted: {}",
                relative.display()
            )));
        }
        let output_path = destination.join(&relative);
        if entry.is_dir() {
            fs::create_dir_all(&output_path)
                .map_err(|source| io_error("create archive directory", &output_path, source))?;
            continue;
        }
        extracted = bounded_add(extracted, entry.size(), &relative)?;
        if let Some(parent) = output_path.parent() {
            fs::create_dir_all(parent)
                .map_err(|source| io_error("create archive directory", parent, source))?;
        }
        let mut output = OpenOptions::new()
            .create_new(true)
            .write(true)
            .open(&output_path)
            .map_err(|source| io_error("create extracted file", &output_path, source))?;
        std::io::copy(&mut entry, &mut output)
            .map_err(|source| io_error("extract runtime file", &output_path, source))?;
    }
    Ok(())
}

fn bounded_add(total: u64, size: u64, path: &Path) -> Result<u64, RuntimeError> {
    let total = total.checked_add(size).ok_or_else(|| {
        RuntimeError::UnsafeArchive(format!("expanded size overflow at {}", path.display()))
    })?;
    if total > MAX_EXTRACTED_BYTES {
        return Err(RuntimeError::UnsafeArchive(format!(
            "expanded archive exceeds {MAX_EXTRACTED_BYTES} bytes"
        )));
    }
    Ok(total)
}

fn validate_relative_path(path: &Path) -> Result<(), RuntimeError> {
    if path.as_os_str().is_empty()
        || path
            .components()
            .any(|component| !matches!(component, Component::Normal(_) | Component::CurDir))
    {
        return Err(RuntimeError::UnsafeArchive(path.display().to_string()));
    }
    Ok(())
}

fn validate_symlink_target(path: &Path, target: &Path) -> Result<(), RuntimeError> {
    if target.is_absolute() {
        return Err(RuntimeError::UnsafeArchive(format!(
            "{} points outside the install root",
            path.display()
        )));
    }
    let mut depth = path.parent().map_or(0, |parent| {
        parent
            .components()
            .filter(|component| matches!(component, Component::Normal(_)))
            .count()
    });
    for component in target.components() {
        match component {
            Component::Normal(_) => depth += 1,
            Component::CurDir => {}
            Component::ParentDir if depth > 0 => depth -= 1,
            _ => {
                return Err(RuntimeError::UnsafeArchive(format!(
                    "{} has unsafe symlink target {}",
                    path.display(),
                    target.display()
                )));
            }
        }
    }
    Ok(())
}

fn collect_entries(root: &Path) -> Result<Vec<InstalledEntry>, RuntimeError> {
    fn walk(
        root: &Path,
        directory: &Path,
        entries: &mut Vec<InstalledEntry>,
    ) -> Result<(), RuntimeError> {
        let children = fs::read_dir(directory)
            .map_err(|source| io_error("inspect runtime install", directory, source))?;
        for child in children {
            let child =
                child.map_err(|source| io_error("inspect runtime install", directory, source))?;
            let path = child.path();
            let relative = path
                .strip_prefix(root)
                .expect("walked path remains beneath root")
                .to_path_buf();
            if relative == Path::new(MANIFEST_FILE) {
                continue;
            }
            let metadata = fs::symlink_metadata(&path)
                .map_err(|source| io_error("inspect runtime entry", &path, source))?;
            if metadata.is_dir() {
                walk(root, &path, entries)?;
            } else if metadata.is_file() {
                let (sha256, size_bytes) = hash_file(&path)?;
                entries.push(InstalledEntry::File {
                    path: relative,
                    sha256,
                    size_bytes,
                });
            } else if metadata.file_type().is_symlink() {
                let target = fs::read_link(&path)
                    .map_err(|source| io_error("read runtime symlink", &path, source))?;
                validate_symlink_target(&relative, &target)?;
                entries.push(InstalledEntry::Symlink {
                    path: relative,
                    target,
                });
            } else {
                return Err(RuntimeError::InvalidInstall(format!(
                    "unsupported installed entry {}",
                    relative.display()
                )));
            }
        }
        Ok(())
    }

    let mut entries = Vec::new();
    walk(root, root, &mut entries)?;
    entries.sort_by(|left, right| entry_path(left).cmp(entry_path(right)));
    Ok(entries)
}

fn entry_path(entry: &InstalledEntry) -> &Path {
    match entry {
        InstalledEntry::File { path, .. } | InstalledEntry::Symlink { path, .. } => path,
    }
}

fn write_manifest(root: &Path, manifest: &InstallManifest) -> Result<(), RuntimeError> {
    let path = root.join(MANIFEST_FILE);
    let bytes = serde_json::to_vec_pretty(manifest)?;
    let mut file = OpenOptions::new()
        .create_new(true)
        .write(true)
        .open(&path)
        .map_err(|source| io_error("create runtime manifest", &path, source))?;
    file.write_all(&bytes)
        .and_then(|()| file.sync_all())
        .map_err(|source| io_error("write runtime manifest", &path, source))
}

fn validate_install(root: &Path, artifact: &RuntimeArtifact) -> Result<PathBuf, RuntimeError> {
    let root_metadata = fs::symlink_metadata(root).map_err(|error| {
        RuntimeError::InvalidInstall(format!("cannot inspect install root: {error}"))
    })?;
    if !root_metadata.is_dir() || root_metadata.file_type().is_symlink() {
        return Err(RuntimeError::InvalidInstall(format!(
            "{} is not a directory",
            root.display()
        )));
    }
    let manifest_path = root.join(MANIFEST_FILE);
    let bytes = fs::read(&manifest_path)
        .map_err(|error| RuntimeError::InvalidInstall(format!("cannot read manifest: {error}")))?;
    let manifest: InstallManifest = serde_json::from_slice(&bytes)
        .map_err(|error| RuntimeError::InvalidInstall(format!("invalid manifest: {error}")))?;
    if manifest.schema_version != 1
        || manifest.release != LLAMA_CPP_RELEASE
        || manifest.commit != LLAMA_CPP_COMMIT
        || manifest.platform != artifact.platform
        || manifest.backend != artifact.backend
        || !manifest
            .archive_sha256
            .eq_ignore_ascii_case(&artifact.spec.sha256)
        || manifest.server_relative_path != artifact.server_relative_path
    {
        return Err(RuntimeError::InvalidInstall(
            "manifest identity does not match the pinned runtime".to_owned(),
        ));
    }
    let current =
        collect_entries(root).map_err(|error| RuntimeError::InvalidInstall(error.to_string()))?;
    if current != manifest.entries {
        return Err(RuntimeError::InvalidInstall(
            "installed runtime files differ from the integrity manifest".to_owned(),
        ));
    }
    let executable = root.join(&manifest.server_relative_path);
    if !executable.is_file() {
        return Err(RuntimeError::InvalidInstall(
            "server executable is missing".to_owned(),
        ));
    }
    Ok(executable)
}

#[cfg(unix)]
fn make_executable(path: &Path) -> Result<(), RuntimeError> {
    use std::os::unix::fs::PermissionsExt;

    let mut permissions = fs::metadata(path)
        .map_err(|source| io_error("inspect server executable", path, source))?
        .permissions();
    permissions.set_mode(permissions.mode() | 0o700);
    fs::set_permissions(path, permissions)
        .map_err(|source| io_error("mark server executable", path, source))
}

#[cfg(not(unix))]
fn make_executable(_path: &Path) -> Result<(), RuntimeError> {
    Ok(())
}

fn quarantine_directory(path: &Path) -> Result<(), RuntimeError> {
    let file_name = path
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| RuntimeError::InvalidInstall(path.display().to_string()))?;
    let target = path.with_file_name(format!(".{file_name}.invalid-{}", Uuid::new_v4()));
    fs::rename(path, &target).map_err(|source| io_error("quarantine invalid runtime", path, source))
}

fn io_error(operation: &'static str, path: &Path, source: std::io::Error) -> RuntimeError {
    RuntimeError::Io {
        operation,
        path: path.to_path_buf(),
        source,
    }
}

struct DirectoryLock {
    file: File,
}

impl DirectoryLock {
    fn acquire(path: &Path, timeout: Duration) -> Result<Self, RuntimeError> {
        let started = Instant::now();
        match fs::symlink_metadata(path) {
            Ok(metadata) if metadata.file_type().is_symlink() => {
                return Err(RuntimeError::InvalidInstall(format!(
                    "runtime lock must not be a symlink: {}",
                    path.display()
                )));
            }
            Ok(_) => {}
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(source) => return Err(io_error("inspect runtime install lock", path, source)),
        }
        let file = OpenOptions::new()
            .create(true)
            .read(true)
            .write(true)
            .truncate(false)
            .open(path)
            .map_err(|source| io_error("open runtime install lock", path, source))?;
        loop {
            match FileExt::try_lock_exclusive(&file) {
                Ok(()) => return Ok(Self { file }),
                Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
                    if started.elapsed() >= timeout {
                        return Err(RuntimeError::LockTimeout {
                            path: path.to_path_buf(),
                            seconds: timeout.as_secs(),
                        });
                    }
                    thread::sleep(Duration::from_millis(50));
                }
                Err(source) => return Err(io_error("lock runtime install", path, source)),
            }
        }
    }
}

impl Drop for DirectoryLock {
    fn drop(&mut self) {
        let _ = FileExt::unlock(&self.file);
    }
}

struct StagingDirectory {
    path: PathBuf,
}

impl StagingDirectory {
    fn create(path: PathBuf) -> Result<Self, RuntimeError> {
        fs::create_dir(&path)
            .map_err(|source| io_error("create runtime staging directory", &path, source))?;
        Ok(Self { path })
    }

    fn path(&self) -> &Path {
        &self.path
    }

    fn publish(&mut self, destination: &Path) -> Result<(), RuntimeError> {
        fs::rename(&self.path, destination)
            .map_err(|source| io_error("publish runtime installation", destination, source))?;
        self.path = PathBuf::new();
        Ok(())
    }
}

impl Drop for StagingDirectory {
    fn drop(&mut self) {
        if !self.path.as_os_str().is_empty() {
            let _ = fs::remove_dir_all(&self.path);
        }
    }
}

#[cfg(test)]
mod tests {
    use std::io::Write;

    use super::{
        Architecture, ArchiveFormat, InstallManifest, LLAMA_CPP_COMMIT, LLAMA_CPP_RELEASE,
        OperatingSystem, RuntimeArtifact, RuntimeBackend, RuntimeError, RuntimePlatform,
        collect_entries, extract_zip, make_executable, runtime_artifact, validate_install,
        validate_symlink_target, write_manifest,
    };
    use crate::artifact::ArtifactSpec;

    #[test]
    fn catalog_is_platform_and_backend_specific() {
        let linux = RuntimePlatform {
            os: OperatingSystem::Linux,
            architecture: Architecture::X86_64,
        };
        let cpu = runtime_artifact(linux, RuntimeBackend::Cpu).expect("cpu");
        let rocm = runtime_artifact(linux, RuntimeBackend::Rocm).expect("rocm");
        assert_ne!(cpu.spec.sha256, rocm.spec.sha256);
        assert!(rocm.spec.file_name.contains("rocm-7.14"));

        let unsupported = RuntimePlatform {
            os: OperatingSystem::Macos,
            architecture: Architecture::Aarch64,
        };
        assert!(matches!(
            runtime_artifact(unsupported, RuntimeBackend::Rocm),
            Err(RuntimeError::UnsupportedTarget { .. })
        ));

        let windows = RuntimePlatform {
            os: OperatingSystem::Windows,
            architecture: Architecture::X86_64,
        };
        assert_eq!(
            runtime_artifact(windows, RuntimeBackend::Cpu)
                .expect("windows cpu")
                .server_relative_path,
            std::path::PathBuf::from("llama-server.exe")
        );
    }

    #[test]
    fn symlink_validation_allows_internal_links_only() {
        assert!(
            validate_symlink_target(
                std::path::Path::new("root/lib.so"),
                std::path::Path::new("lib.so.1")
            )
            .is_ok()
        );
        assert!(
            validate_symlink_target(
                std::path::Path::new("root/lib.so"),
                std::path::Path::new("../../escape")
            )
            .is_err()
        );
        assert!(
            validate_symlink_target(
                std::path::Path::new("root/lib.so"),
                std::path::Path::new("/absolute")
            )
            .is_err()
        );
    }

    #[test]
    fn zip_extraction_rejects_parent_traversal() {
        let directory = tempfile::tempdir().expect("tempdir");
        let archive_path = directory.path().join("unsafe.zip");
        let file = std::fs::File::create(&archive_path).expect("archive");
        let mut archive = zip::ZipWriter::new(file);
        archive
            .start_file(
                "../escape",
                zip::write::SimpleFileOptions::default()
                    .compression_method(zip::CompressionMethod::Stored),
            )
            .expect("entry");
        archive.write_all(b"escape").expect("bytes");
        archive.finish().expect("finish");
        let target = directory.path().join("target");
        std::fs::create_dir(&target).expect("target");

        assert!(matches!(
            extract_zip(&archive_path, &target),
            Err(RuntimeError::UnsafeArchive(_))
        ));
        assert!(!directory.path().join("escape").exists());
        assert_eq!(ArchiveFormat::Zip, ArchiveFormat::Zip);
    }

    #[test]
    fn install_manifest_detects_tampering_before_reuse() {
        let directory = tempfile::tempdir().expect("tempdir");
        let root = directory.path().join("runtime");
        let release_root = root.join(format!("llama-{LLAMA_CPP_RELEASE}"));
        std::fs::create_dir_all(&release_root).expect("release root");
        let executable = release_root.join("llama-server");
        std::fs::write(&executable, b"trusted executable").expect("executable");
        make_executable(&executable).expect("permissions");
        let platform = RuntimePlatform {
            os: OperatingSystem::Linux,
            architecture: Architecture::X86_64,
        };
        let artifact = RuntimeArtifact {
            spec: ArtifactSpec {
                id: "llama.cpp".to_owned(),
                version: LLAMA_CPP_RELEASE.to_owned(),
                file_name: "runtime.tar.gz".to_owned(),
                url: "https://example.invalid/runtime.tar.gz".to_owned(),
                sha256: "a".repeat(64),
                size_bytes: 1,
            },
            platform,
            backend: RuntimeBackend::Cpu,
            archive_format: ArchiveFormat::TarGz,
            server_relative_path: executable
                .strip_prefix(&root)
                .expect("relative")
                .to_path_buf(),
        };
        let manifest = InstallManifest {
            schema_version: 1,
            release: LLAMA_CPP_RELEASE.to_owned(),
            commit: LLAMA_CPP_COMMIT.to_owned(),
            platform,
            backend: RuntimeBackend::Cpu,
            archive_sha256: artifact.spec.sha256.clone(),
            server_relative_path: artifact.server_relative_path.clone(),
            entries: collect_entries(&root).expect("entries"),
        };
        write_manifest(&root, &manifest).expect("manifest");
        assert!(validate_install(&root, &artifact).is_ok());

        std::fs::write(&executable, b"tampered executable").expect("tamper");
        assert!(matches!(
            validate_install(&root, &artifact),
            Err(RuntimeError::InvalidInstall(_))
        ));
    }
}