Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

115 KB
Raw Blame
#!/usr/bin/env python3
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Shared core of the ggml prebuilt installers: verified downloads, safe extraction, install lock,
and descriptor-driven release resolution and activation. Collaborators take an ops handle that
resolves names in the caller's module first, so monkeypatches still apply."""

from __future__ import annotations

import errno
import functools
import hashlib
import http.client
import json
import os
import stat
import random
import re
import shutil
import socket
import subprocess
import sys
import tempfile
import time
import urllib.error
import urllib.parse
import urllib.request
from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Callable, Iterable, Iterator

# Bootstrap studio/ on sys.path: an importlib spec load prepares no path.
if __package__:
    from .backend.utils.auth_safe import AuthSafeRedirectHandler
else:
    _STUDIO_DIR = os.path.dirname(os.path.abspath(__file__))
    if _STUDIO_DIR not in sys.path:
        sys.path.insert(0, _STUDIO_DIR)
    from backend.utils.auth_safe import AuthSafeRedirectHandler

_FILELOCK_CLASSES: tuple[Any, Any] | None = None


def filelock_classes() -> tuple[Any, Any]:
    """``(FileLock, Timeout)``, or ``(None, None)`` when filelock is not installed.

    First use, not import: filelock pulls in asyncio and costs ~25 ms, and only
    ``install_lock`` needs it. Cached because repeating an ImportError is not cheap.
    """
    global _FILELOCK_CLASSES
    if _FILELOCK_CLASSES is None:
        try:
            from filelock import FileLock, Timeout as FileLockTimeout
        except ImportError:
            _FILELOCK_CLASSES = (None, None)
        else:
            _FILELOCK_CLASSES = (FileLock, FileLockTimeout)
    return _FILELOCK_CLASSES


# Gate pasted from native_tls.py inline_gate_source(); test_native_tls_entrypoints.py checks it.
_TRUSTSTORE_VENDOR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "backend", "vendor")
_flag = os.environ.get("UNSLOTH_STUDIO_NATIVE_TLS", "").strip().lower()
_owned = os.environ.get("UNSLOTH_STUDIO_DESKTOP_OWNER_KIND", "") == "tauri"
if _flag in ("1", "true", "yes") or (
    _flag not in ("0", "false", "no")
    and (sys.platform in ("darwin", "win32") or (sys.platform.startswith("linux") and _owned))
):
    try:
        if _TRUSTSTORE_VENDOR not in sys.path:
            sys.path.append(_TRUSTSTORE_VENDOR)
        import truststore
        truststore.inject_into_ssl()
    except Exception:
        pass
del _flag, _owned


class PrebuiltFallback(RuntimeError):
    pass


class ReleaseIntegrityError(PrebuiltFallback):
    """A release that ANSWERED, and the answer was that it cannot be trusted.

    A PrebuiltFallback means "this lookup could not answer", which says nothing about the tree
    already on disk, so the keep-existing paths treat it as a reason to hold the install and
    report success. An asset missing from the checksum index, or a manifest digest that
    disagrees with it, is not that: the release was fetched and found untrustworthy, and
    reporting "update unavailable" over it turns a tamper signal into a routine offline notice.
    A subclass rather than a sibling so every existing `except PrebuiltFallback` still catches
    it; only the keep paths single it out and re-raise.
    """


class BusyInstallConflict(RuntimeError):
    pass


# ── Defaults a component module may override via its own globals ──
USER_AGENT = "unsloth-studio-prebuilt"
GITHUB_AUTH_HOSTS = {"api.github.com", "github.com"}
HF_AUTH_HOSTS = {"huggingface.co", "www.huggingface.co"}
RETRYABLE_HTTP_STATUS = {408, 429, 500, 502, 503, 504}
GITHUB_RATE_LIMIT_STATUS = {403, 429}
HTTP_FETCH_ATTEMPTS = 4
HTTP_FETCH_BASE_DELAY_SECONDS = 0.75
JSON_FETCH_ATTEMPTS = 3
TTY_PROGRESS_START_DELAY_SECONDS = 0.5
INSTALL_LOCK_TIMEOUT_SECONDS = 300
# Settle is only an optimisation, so wait briefly rather than the full install timeout.
SETTLE_LOCK_TIMEOUT_SECONDS = 5
INSTALL_STAGING_ROOT_NAME = ".staging"
SCHEMA_VERSION = 1
FALLBACK_BACKEND: str | None = "cpu"
_RATE_LIMIT_WAIT_CAP_SECONDS = 60.0

# Lowest CUDA major shipped; higher majors are probed generically by naming convention.
_MIN_CUDA_MAJOR = 12
_MAX_PROBE_CUDA_MAJOR = 19

# Toolkit 12.8+ prebuilts use nvcc -compress-mode=size, "not compatible with drivers released
# before CUDA Toolkit's 12.4 Release" (nvcc docs): every kernel load fails (#12842).
_COMPRESSED_FATBIN_MIN_DRIVER = (12, 4)

# Blackwell floor is sm_100 (B100/B200 sm_100, B300/GB300 sm_103 below consumer
# RTX 50 sm_120); the family needs toolkit >= 12.8, sm_103/sm_121 need 12.9.
_BLACKWELL_MIN_SM = 100
_BLACKWELL_MIN_TOOLKIT = (12, 8)
_BLACKWELL_SM_MIN_TOOLKIT = {103: (12, 9), 121: (12, 9)}


def log(message: str) -> None:
    print(f"[prebuilt-core] {message}", file = sys.stderr)


def _cuda_runtime_lines_for_major(major: int) -> list[str]:
    """Runtime lines a driver of this CUDA major can use (its own major and any
    older one, newest first down to the minimum we ship)."""
    return [f"cuda{m}" for m in range(major, _MIN_CUDA_MAJOR - 1, -1)]


# ── The ops seam ──
_MISSING = object()

# Core functions taking ops first; installer wrappers and test monkeypatches win over defaults.
_OPS_FIRST_NAMES = {
    "auth_headers",
    "github_api_headers",
    "download_bytes",
    "fetch_json",
    "download_file",
    "download_file_verified",
    "download_file_verified_strict",
    "github_release",
    "github_release_assets",
    "download_host_latest_release_tag",
    "fetch_download_host_json",
    "linux_runtime_dirs_for_required_libraries",
    "detected_linux_runtime_lines",
    "detected_windows_runtime_lines",
    "parse_manifest",
    "parse_release_checksums",
    "fetch_release_checksums",
    "expected_sha256_for",
    "macos_min_os_ok",
    "artifacts_for_host",
    "select_artifact",
    "select_artifact_with_fallback",
    "auto_detect_backend",
    "resolve_backend",
    "fetch_release_bundle",
    "asset_download_url",
    "resolve_newest_release_tag",
    "resolve_release_tag",
    "resolve_release_via_download_host",
    "fetch_release_for_install",
    "write_prebuilt_metadata",
    "load_prebuilt_metadata",
    "existing_install_matches",
    "marker_install_fingerprint",
    "WalkBack",
    "WALK_BACK_KEYS",
    "macos_version_label",
    "walk_back_for",
    "marker_walk_back",
    "walk_back_stands",
    "walk_back_patch",
    "metadata_path",
    "selection_from_artifact",
    "plan_selection",
    "install_from_bundle",
    "install_prebuilt",
    "resolve_prebuilt",
    "installed_server_path",
    "assemble_install_tree",
    "validate_staged_server",
    "locate_server_in_tree",
    "_download_host_latest_release_tag",
    "_download_host_json",
    "_resolve_release_via_download_host",
    "_install_from_bundle",
}


class ModuleOps:
    """Late-binding name resolver over an installer module's globals.

    Lookup hits the wrapped globals first (so a ``monkeypatch.setattr`` is always
    observed), then this module's defaults (ops-first defaults come back bound).
    """

    def __init__(self, module_globals: dict[str, Any]) -> None:
        self._globals = module_globals

    def __getattr__(self, name: str) -> Any:
        value = self._globals.get(name, _MISSING)
        if value is _MISSING:
            value = globals().get(name, _MISSING)
            if value is _MISSING:
                raise AttributeError(f"prebuilt component namespace has no attribute {name!r}")
            if name in _OPS_FIRST_NAMES:
                return functools.partial(value, self)
        return value


@dataclass(frozen = True)
class ComponentDescriptor:
    """Everything the generic flow needs about one ggml-family component.

    Hooks mirror the module-level names an installer defines; a descriptor-only
    component supplies them here and ``component_ops`` builds a namespace with
    core defaults behind them.
    """

    component: str  # manifest "component" value, e.g. "whisper.cpp"
    log_prefix: str  # stderr prefix, e.g. "whisper-prebuilt"
    published_repo: str  # fork publishing the prebuilt releases
    manifest_asset_name: str
    sha256_asset_name: str
    metadata_filename: str  # marker written into the install dir
    user_agent: str
    supported_backends: tuple[str, ...] = ("cpu", "cuda", "metal", "vulkan", "rocm")
    schema_version: int = SCHEMA_VERSION
    # None (llama) reports no prebuilt so the caller falls back to a source build.
    fallback_backend: str | None = "cpu"
    staging_root_name: str = INSTALL_STAGING_ROOT_NAME
    run_staged_validation: bool = False
    # Hooks; None keeps the core default.
    detect_host: Callable[[], Any] | None = None
    host_platform_tokens: Callable[[Any], tuple[str, str]] | None = None
    server_binary_name: Callable[[Any], str] | None = None
    runtime_bin_dir: Callable[[Path, Any], Path] | None = None
    auto_detect_backend: Callable[[Any], str] | None = None


def component_namespace(descriptor: ComponentDescriptor) -> dict[str, Any]:
    """Materialize a descriptor into the module-like namespace ``ModuleOps``
    resolves against; core defaults cover anything not listed here."""
    prefix = descriptor.log_prefix

    def component_log(message: str) -> None:
        print(f"[{prefix}] {message}", file = sys.stderr)

    namespace: dict[str, Any] = {
        "COMPONENT": descriptor.component,
        "SCHEMA_VERSION": descriptor.schema_version,
        "DEFAULT_PUBLISHED_REPO": descriptor.published_repo,
        "MANIFEST_ASSET_NAME": descriptor.manifest_asset_name,
        "SHA256_ASSET_NAME": descriptor.sha256_asset_name,
        "METADATA_FILENAME": descriptor.metadata_filename,
        "SUPPORTED_BACKENDS": descriptor.supported_backends,
        "USER_AGENT": descriptor.user_agent,
        "FALLBACK_BACKEND": descriptor.fallback_backend,
        "INSTALL_STAGING_ROOT_NAME": descriptor.staging_root_name,
        "_RUN_STAGED_PREBUILT_VALIDATION": descriptor.run_staged_validation,
        "log": component_log,
    }
    for hook in (
        "detect_host",
        "host_platform_tokens",
        "server_binary_name",
        "runtime_bin_dir",
        "auto_detect_backend",
    ):
        value = getattr(descriptor, hook)
        if value is not None:
            namespace[hook] = value
    return namespace


def component_ops(descriptor: ComponentDescriptor) -> ModuleOps:
    return ModuleOps(component_namespace(descriptor))


# ── Lock/busy classification ──
def _os_error_messages(exc: BaseException) -> list[str]:
    messages: list[str] = []
    if isinstance(exc, OSError):
        for value in (
            getattr(exc, "strerror", None),
            getattr(exc, "filename", None),
            getattr(exc, "filename2", None),
        ):
            if isinstance(value, str) and value:
                messages.append(value)
    text = str(exc)
    if text:
        messages.append(text)
    return [message.lower() for message in messages if message]


def is_busy_lock_error(exc: BaseException) -> bool:
    if isinstance(exc, BusyInstallConflict):
        return True
    if isinstance(exc, OSError):
        if exc.errno in {
            errno.EACCES,
            errno.EBUSY,
            errno.EPERM,
            errno.ETXTBSY,
        }:
            return True
        if getattr(exc, "winerror", None) in {5, 32, 145}:
            return True
    for message in _os_error_messages(exc):
        if any(
            needle in message
            for needle in (
                "access is denied",
                "being used by another process",
                "device or resource busy",
                "permission denied",
                "text file busy",
                "file is in use",
                "process cannot access the file",
                "cannot create a file when that file already exists",
            )
        ):
            return True
    return False


# ── HTTP: auth, redirects, retries ──
def parsed_hostname(url: str | None) -> str | None:
    if not url:
        return None
    try:
        hostname = urllib.parse.urlparse(url).hostname
    except Exception:
        return None
    if not hostname:
        return None
    return hostname.lower()


def should_send_github_auth(url: str | None) -> bool:
    return parsed_hostname(url) in GITHUB_AUTH_HOSTS


def should_send_hf_auth(url: str | None) -> bool:
    return parsed_hostname(url) in HF_AUTH_HOSTS


def auth_headers(ops: ModuleOps, url: str | None = None) -> dict[str, str]:
    headers = {
        "User-Agent": ops.USER_AGENT,
    }
    token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")
    if token and should_send_github_auth(url):
        headers["Authorization"] = f"Bearer {token}"
        return headers
    # Anonymous HF fetches share a per-IP rate limit (429).
    hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
    if hf_token and should_send_hf_auth(url):
        headers["Authorization"] = f"Bearer {hf_token}"
    return headers


_CrossHostAuthStrippingRedirectHandler = AuthSafeRedirectHandler
_URL_OPENER = urllib.request.build_opener(AuthSafeRedirectHandler())


def github_api_headers(ops: ModuleOps, url: str | None = None) -> dict[str, str]:
    return {
        "Accept": "application/vnd.github+json",
        **ops.auth_headers(url),
    }


def is_github_api_url(url: str | None) -> bool:
    return parsed_hostname(url) == "api.github.com"


def is_retryable_url_error(exc: Exception) -> bool:
    if isinstance(exc, urllib.error.HTTPError):
        if exc.code == 403:
            return (
                is_github_api_url(getattr(exc, "url", None))
                and _http_error_retry_delay(exc) is not None
            )
        return exc.code in RETRYABLE_HTTP_STATUS
    if isinstance(exc, urllib.error.URLError):
        return True
    if isinstance(exc, TimeoutError):
        return True
    if isinstance(exc, socket.timeout):
        return True
    # Raw ConnectionError/IncompleteRead bypass URLError and would skip retries.
    if isinstance(exc, (ConnectionError, http.client.IncompleteRead)):
        return True
    return False


def _http_error_retry_delay(exc: Exception) -> float | None:
    """Recommended wait from rate-limit headers on a 403 or 429; None when no header is present or
    the wait exceeds _RATE_LIMIT_WAIT_CAP_SECONDS, since the source build fallback is faster."""
    if not isinstance(exc, urllib.error.HTTPError):
        return None
    headers = getattr(exc, "headers", None)
    if headers is None:
        return None
    retry_after = headers.get("Retry-After")
    if retry_after and retry_after.strip().isdigit():
        wait = float(retry_after.strip())
        return wait if wait <= _RATE_LIMIT_WAIT_CAP_SECONDS else None
    rate_reset = headers.get("X-RateLimit-Reset")
    if rate_reset and rate_reset.strip().isdigit():
        wait = float(rate_reset.strip()) - time.time()
        if 0.0 < wait <= _RATE_LIMIT_WAIT_CAP_SECONDS:
            return wait + 1.0  # +1s of slack so the bucket is fresh
    return None


def sleep_backoff(
    attempt: int,
    *,
    base_delay: float = HTTP_FETCH_BASE_DELAY_SECONDS,
    exc: Exception | None = None,
) -> None:
    delay = base_delay * (2 ** max(attempt - 1, 0))
    header_delay = _http_error_retry_delay(exc) if exc is not None else None
    if header_delay is not None:
        delay = max(delay, header_delay)
    delay += random.uniform(0.0, 0.2)
    time.sleep(delay)


# ── Atomic writes and hashing ──
def make_staging_dir(parent: Path, prefix: str) -> Path:
    """``tempfile.mkdtemp``, except a Windows dir inherits ``parent``'s ACL.

    mkdtemp's 0o700 gives a Windows dir a protected SYSTEM / Administrators / OWNER RIGHTS DACL
    (CPython gh-118486), and a tree renamed out of it keeps those entries. An elevated run owns it
    as Administrators, so the same account cannot read it unelevated (#14052, #9928).
    """
    if sys.platform != "win32":
        return Path(tempfile.mkdtemp(prefix = prefix, dir = str(parent)))
    for _ in range(100):
        path = Path(parent) / f"{prefix}{os.urandom(6).hex()}"
        try:
            os.mkdir(path)
        except FileExistsError:
            continue
        return path
    raise FileExistsError(f"no free staging name under {parent}")


def atomic_write_bytes(destination: Path, data: bytes) -> None:
    destination.parent.mkdir(parents = True, exist_ok = True)
    with tempfile.NamedTemporaryFile(
        prefix = destination.name + ".tmp-",
        dir = destination.parent,
        delete = False,
    ) as handle:
        tmp_path = Path(handle.name)
        handle.write(data)
        handle.flush()
        os.fsync(handle.fileno())
    os.replace(tmp_path, destination)


def atomic_replace_from_tempfile(
    tmp_path: Path,
    destination: Path,
    *,
    attempts: int = 8,
) -> None:
    """Retries os.replace on transient Windows sharing violations: rename-over needs DELETE access
    that a scanner or indexer holding the marker open denies; other errors raise at once."""
    destination.parent.mkdir(parents = True, exist_ok = True)
    delay = 0.25
    for attempt in range(attempts):
        try:
            os.replace(tmp_path, destination)
            return
        except OSError as exc:
            transient = os.name == "nt" and getattr(exc, "winerror", None) in (5, 32, 145)
            if not transient or attempt == attempts - 1:
                raise
            log(f"marker swap blocked ({exc.winerror}), retrying in {delay:.2f}s")
            time.sleep(delay)
            delay = min(delay * 2, 4.0)


def write_live_marker(marker_path: Path, marker: dict[str, Any]) -> None:
    """Rewrite a marker that is already in service, keeping its mode and owner.

    Temp-and-replace, so a write that fails part-way leaves the valid marker it found;
    and the mode and owner restored on the temp file BEFORE the swap, since os.replace
    keeps the source file's, and NamedTemporaryFile's 0600 would leave a group-shared
    install's marker readable only by whoever ran this update. Mirrors the llama
    installer's marker writer. Raises on failure; callers decide what a failed
    refresh costs.
    """
    data = (json.dumps(marker, indent = 2) + "\n").encode("utf-8")
    try:
        original = marker_path.stat()
    except OSError:
        original = None
    tmp_path: Path | None = None
    try:
        with tempfile.NamedTemporaryFile(
            prefix = marker_path.name + ".tmp-",
            dir = marker_path.parent,
            delete = False,
        ) as handle:
            tmp_path = Path(handle.name)
            handle.write(data)
            handle.flush()
            os.fsync(handle.fileno())
        if original is not None:
            os.chmod(tmp_path, stat.S_IMODE(original.st_mode))
            # chown owner+group is all-or-nothing, so fall back to group alone for non-root members.
            try:
                os.chown(tmp_path, original.st_uid, original.st_gid)
            except (OSError, AttributeError):
                try:
                    os.chown(tmp_path, -1, original.st_gid)
                except (OSError, AttributeError):
                    pass
        atomic_replace_from_tempfile(tmp_path, marker_path)
    except BaseException:
        if tmp_path is not None:
            try:
                tmp_path.unlink()
            except OSError:
                pass
        raise


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def sha256_bytes(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def normalize_sha256_digest(value: str | None) -> str | None:
    if not isinstance(value, str) or not value:
        return None
    lowered = value.lower()
    if lowered.startswith("sha256:"):
        lowered = lowered.split(":", 1)[1]
    if len(lowered) != 64 or any(ch not in "0123456789abcdef" for ch in lowered):
        return None
    return lowered


def validate_schema_version(
    payload: dict[str, Any],
    *,
    label: str,
    schema_version: int = SCHEMA_VERSION,
    error: type[Exception] = RuntimeError,
) -> None:
    value = payload.get("schema_version")
    if value is None:
        return
    try:
        normalized = int(value)
    except (TypeError, ValueError) as exc:
        raise error(f"{label} schema_version was not an integer") from exc
    if normalized != schema_version:
        raise error(f"{label} schema_version={normalized} is unsupported")


# ── Download progress ──
def format_byte_count(num_bytes: float) -> str:
    units = ["B", "KiB", "MiB", "GiB", "TiB"]
    value = float(num_bytes)
    for unit in units:
        if abs(value) < 1024.0 or unit == units[-1]:
            if unit == "B":
                return f"{int(value)} {unit}"
            return f"{value:.1f} {unit}"
        value /= 1024.0
    return f"{num_bytes:.1f} B"


def _progress_percent_step() -> int:
    """Non-tty milestone granularity. The in-app updater sets
    UNSLOTH_PROGRESS_PERCENT_STEP=5 for finer progress lines."""
    try:
        step = int(os.environ.get("UNSLOTH_PROGRESS_PERCENT_STEP", "25"))
    except ValueError:
        return 25
    return min(max(step, 1), 50)


class DownloadProgress:
    def __init__(self, label: str, total_bytes: int | None) -> None:
        self.label = label
        self.total_bytes = total_bytes if total_bytes and total_bytes > 0 else None
        self.start_time = time.monotonic()
        self.last_emit = 0.0
        term_ok = os.environ.get("TERM", "").lower() != "dumb"
        self.stream = (
            sys.stderr if sys.stderr.isatty() else sys.stdout if sys.stdout.isatty() else sys.stderr
        )
        self.is_tty = term_ok and self.stream.isatty()
        self.completed = False
        self.milestone_step = _progress_percent_step()
        self.last_milestone_percent = -1
        self.last_milestone_bytes = 0
        self.has_rendered_tty_progress = False

    def _render(
        self,
        downloaded_bytes: int,
        *,
        final: bool = False,
    ) -> str:
        elapsed = max(time.monotonic() - self.start_time, 1e-6)
        speed = downloaded_bytes / elapsed
        speed_text = f"{format_byte_count(speed)}/s"
        if self.total_bytes is not None:
            percent = min(100.0, (downloaded_bytes / self.total_bytes) * 100.0)
            return (
                f"{self.label}: {percent:5.1f}% "
                f"({format_byte_count(downloaded_bytes)}/{format_byte_count(self.total_bytes)}) "
                f"at {speed_text}"
            )
        if final:
            return f"{self.label}: {format_byte_count(downloaded_bytes)} downloaded at {speed_text}"
        return f"{self.label}: {format_byte_count(downloaded_bytes)} downloaded at {speed_text}"

    def update(self, downloaded_bytes: int) -> None:
        now = time.monotonic()
        if self.is_tty:
            elapsed = now - self.start_time
            if not self.has_rendered_tty_progress:
                if self.total_bytes is not None and downloaded_bytes >= self.total_bytes:
                    return
                if elapsed < TTY_PROGRESS_START_DELAY_SECONDS:
                    return
            min_interval = 0.2
            if (
                self.has_rendered_tty_progress
                and not self.completed
                and (now - self.last_emit) < min_interval
            ):
                return
            self.last_emit = now
            line = self._render(downloaded_bytes)
            self.stream.write("\r\033[K" + line)
            self.stream.flush()
            self.has_rendered_tty_progress = True
            return

        should_emit = False
        if self.total_bytes is not None:
            percent = int((downloaded_bytes * 100) / max(self.total_bytes, 1))
            step = self.milestone_step
            milestone_percent = min((percent // step) * step, 100)
            if milestone_percent > self.last_milestone_percent and milestone_percent < 100:
                self.last_milestone_percent = milestone_percent
                should_emit = True
        else:
            byte_step = 25 * 1024 * 1024
            if (
                downloaded_bytes - self.last_milestone_bytes >= byte_step
                and (now - self.last_emit) >= 5.0
            ):
                self.last_milestone_bytes = downloaded_bytes
                should_emit = True

        if not should_emit:
            return

        self.last_emit = now
        self.stream.write(self._render(downloaded_bytes) + "\n")
        self.stream.flush()

    def finish(self, downloaded_bytes: int) -> None:
        self.completed = True
        line = self._render(downloaded_bytes, final = True)
        if self.is_tty:
            if not self.has_rendered_tty_progress:
                return
            self.stream.write("\r\033[K")
        else:
            self.stream.write(line + "\n")
        self.stream.flush()


class TruncatedDownload(http.client.IncompleteRead):
    """The server closed the body before Content-Length bytes arrived. http.client's read(amt)
    returns b"" here instead of raising, so without this a short file is hashed as if whole."""

    def __init__(self, received: int, expected: int) -> None:
        super().__init__(b"", expected - received)
        self.received = received
        self.expected = expected

    def __str__(self) -> str:
        return f"connection closed after {self.received} of {self.expected} bytes"

    __repr__ = __str__


class StalledDownload(TimeoutError):
    """The body is still arriving but too slowly to finish; the socket timeout never fires on a
    trickle, so one stalled connection could otherwise hold an install for an hour."""


# Bytes that must arrive per window, else the attempt is abandoned and retried on a new connection.
DOWNLOAD_STALL_WINDOW_SECONDS = 60.0
DOWNLOAD_STALL_MIN_BYTES = 256 * 1024


def copy_response_body(
    response: Any,
    write: Callable[[bytes], Any],
    *,
    total_bytes: int | None,
    progress: "DownloadProgress | None" = None,
    chunk_size: int = 1024 * 1024,
) -> int:
    """Streams response into write and returns the byte count, raising retryable StalledDownload or
    TruncatedDownload; a real HTTPResponse uses read1 because read(n) waits for all n bytes and
    would never reach the stall window check; progress lands at chunk_size boundaries."""
    per_receive = isinstance(response, http.client.HTTPResponse)
    read = response.read1 if per_receive else response.read
    downloaded = 0
    next_report = chunk_size
    window_start = time.monotonic()
    window_bytes = 0
    while True:
        chunk = read(next_report - downloaded if per_receive else chunk_size)
        if not chunk:
            break
        write(chunk)
        downloaded += len(chunk)
        window_bytes += len(chunk)
        if downloaded >= next_report or not per_receive:
            if progress is not None:
                progress.update(downloaded)
            while next_report <= downloaded:
                next_report += chunk_size
        now = time.monotonic()
        if now - window_start >= DOWNLOAD_STALL_WINDOW_SECONDS:
            if window_bytes < DOWNLOAD_STALL_MIN_BYTES and (
                total_bytes is None or downloaded < total_bytes
            ):
                raise StalledDownload(
                    f"download stalled: {window_bytes} bytes in the last "
                    f"{now - window_start:.0f}s ({downloaded} received so far)"
                )
            window_start = now
            window_bytes = 0
    if progress is not None:
        progress.finish(downloaded)
    if total_bytes is not None and downloaded < total_bytes:
        raise TruncatedDownload(downloaded, total_bytes)
    return downloaded


def download_label_from_url(url: str) -> str:
    name = Path(urllib.parse.urlparse(url).path).name
    return name or url


# ── Downloads ──
def download_bytes(
    ops: ModuleOps,
    url: str,
    *,
    timeout: int = 120,
    attempts: int | None = None,
    headers: dict[str, str] | None = None,
    progress_label: str | None = None,
) -> bytes:
    if attempts is None:
        attempts = ops.HTTP_FETCH_ATTEMPTS
    last_exc: Exception | None = None
    for attempt in range(1, attempts + 1):
        try:
            request = urllib.request.Request(url, headers = headers or ops.auth_headers(url))
            with ops._URL_OPENER.open(request, timeout = timeout) as response:
                total_bytes: int | None = None
                content_length = response.headers.get("Content-Length")
                if content_length and content_length.isdigit():
                    total_bytes = int(content_length)
                progress = DownloadProgress(progress_label, total_bytes) if progress_label else None
                data = bytearray()
                copy_response_body(
                    response, data.extend, total_bytes = total_bytes, progress = progress
                )
                return bytes(data)
        except Exception as exc:
            last_exc = exc
            if attempt >= attempts or not is_retryable_url_error(exc):
                raise
            ops.log(f"fetch failed ({attempt}/{attempts}) for {url}: {exc}; retrying")
            sleep_backoff(attempt, exc = exc)
    assert last_exc is not None
    raise last_exc


def fetch_json(ops: ModuleOps, url: str) -> Any:
    attempts = ops.JSON_FETCH_ATTEMPTS if is_github_api_url(url) else 1
    last_decode_exc: Exception | None = None
    for attempt in range(1, attempts + 1):
        try:
            data = ops.download_bytes(
                url,
                timeout = 30,
                headers = ops.github_api_headers(url)
                if is_github_api_url(url)
                else ops.auth_headers(url),
            )
        except urllib.error.HTTPError as exc:
            # GitHub signals rate limits with 403 or 429.
            if exc.code in GITHUB_RATE_LIMIT_STATUS and is_github_api_url(url):
                hint = ""
                if not (os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")):
                    hint = "; set GH_TOKEN or GITHUB_TOKEN to avoid GitHub API rate limits"
                raise RuntimeError(f"GitHub API returned {exc.code} for {url}{hint}") from exc
            raise
        if not data:
            last_decode_exc = RuntimeError(f"downloaded empty JSON payload from {url}")
        else:
            try:
                payload = json.loads(data.decode("utf-8"))
            except (UnicodeDecodeError, json.JSONDecodeError) as exc:
                last_decode_exc = RuntimeError(f"downloaded invalid JSON from {url}: {exc}")
            else:
                if not isinstance(payload, dict) and not isinstance(payload, list):
                    raise RuntimeError(
                        f"downloaded unexpected JSON type from {url}: {type(payload).__name__}"
                    )
                return payload
        if attempt >= attempts:
            assert last_decode_exc is not None
            raise last_decode_exc
        ops.log(f"json fetch failed ({attempt}/{attempts}) for {url}; retrying")
        sleep_backoff(attempt)
    assert last_decode_exc is not None
    raise last_decode_exc


def download_file(ops: ModuleOps, url: str, destination: Path) -> None:
    destination.parent.mkdir(parents = True, exist_ok = True)
    attempts = ops.HTTP_FETCH_ATTEMPTS
    last_exc: Exception | None = None
    for attempt in range(1, attempts + 1):
        tmp_path: Path | None = None
        try:
            request = urllib.request.Request(url, headers = ops.auth_headers(url))
            with tempfile.NamedTemporaryFile(
                prefix = destination.name + ".tmp-",
                dir = destination.parent,
                delete = False,
            ) as handle:
                tmp_path = Path(handle.name)
                with ops._URL_OPENER.open(request, timeout = 120) as response:
                    total_bytes: int | None = None
                    content_length = response.headers.get("Content-Length")
                    if content_length and content_length.isdigit():
                        total_bytes = int(content_length)
                    progress = DownloadProgress(f"Downloading {destination.name}", total_bytes)
                    copy_response_body(
                        response, handle.write, total_bytes = total_bytes, progress = progress
                    )
                handle.flush()
                os.fsync(handle.fileno())
            if not tmp_path.exists() or tmp_path.stat().st_size == 0:
                raise RuntimeError(f"downloaded empty file from {url}")
            atomic_replace_from_tempfile(tmp_path, destination)
            return
        except Exception as exc:
            last_exc = exc
            if tmp_path is not None:
                try:
                    tmp_path.unlink(missing_ok = True)
                except Exception:
                    pass
            if attempt >= attempts or not is_retryable_url_error(exc):
                raise
            ops.log(f"download failed ({attempt}/{attempts}) for {url}: {exc}; retrying")
            sleep_backoff(attempt, exc = exc)
    assert last_exc is not None
    raise last_exc


def download_file_verified(
    ops: ModuleOps, url: str, destination: Path, *, expected_sha256: str | None, label: str
) -> None:
    normalized_expected = normalize_sha256_digest(expected_sha256)
    if not normalized_expected:
        ops.download_file(url, destination)
        ops.log(f"downloaded {label} without a published sha256; relying on install validation")
        return

    for attempt in range(1, 3):
        ops.download_file(url, destination)
        actual_sha256 = ops.sha256_file(destination)
        if actual_sha256 == normalized_expected:
            ops.log(f"verified {label} sha256={actual_sha256}")
            return

        ops.log(
            f"{label} checksum mismatch on attempt {attempt}/2: "
            f"expected={normalized_expected} actual={actual_sha256}"
        )
        destination.unlink(missing_ok = True)
        if attempt == 2:
            raise PrebuiltFallback(
                f"{label} checksum mismatch after retry: expected={normalized_expected} actual={actual_sha256}"
            )
        ops.log(f"retrying {label} download after checksum mismatch")


def download_file_verified_strict(
    ops: ModuleOps, url: str, destination: Path, *, expected_sha256: str, label: str
) -> None:
    """Verified download with a required digest (the generic flow fails closed on
    a missing checksum, so None never reaches here)."""
    for attempt in range(1, 3):
        ops.download_file(url, destination)
        actual = ops.sha256_file(destination)
        if actual == expected_sha256:
            ops.log(f"verified {label} sha256={actual}")
            return
        ops.log(
            f"{label} checksum mismatch {attempt}/2: expected={expected_sha256} actual={actual}"
        )
        destination.unlink(missing_ok = True)
        if attempt == 2:
            raise PrebuiltFallback(f"{label} checksum mismatch after retry")


# ── GitHub release primitives ──
def release_asset_map(release: dict[str, Any]) -> dict[str, str]:
    assets = release.get("assets")
    if not isinstance(assets, list):
        return {}
    return {
        asset["name"]: asset.get("browser_download_url", "")
        for asset in assets
        if isinstance(asset, dict)
        and isinstance(asset.get("name"), str)
        and isinstance(asset.get("browser_download_url"), str)
    }


def release_asset_digests(release: dict[str, Any]) -> dict[str, str]:
    """Maps asset name to bare sha256 hex from GitHub's digest field, accepting only sha256:
    prefixed digests and skipping others; kept separate from release_asset_map to leave its
    return type alone."""
    assets = release.get("assets")
    if not isinstance(assets, list):
        return {}
    digests: dict[str, str] = {}
    for asset in assets:
        if not isinstance(asset, dict) or not isinstance(asset.get("name"), str):
            continue
        raw = asset.get("digest")
        # Require the prefix: an unprefixed digest has no stated algorithm.
        if not isinstance(raw, str) or not raw.lower().startswith("sha256:"):
            continue
        digest = normalize_sha256_digest(raw)
        if digest:
            digests[asset["name"]] = digest
    return digests


def github_release(
    ops: ModuleOps,
    repo: str,
    tag: str,
    *,
    error: type[Exception] = RuntimeError,
) -> dict[str, Any]:
    payload = ops.fetch_json(
        f"https://api.github.com/repos/{repo}/releases/tags/{urllib.parse.quote(tag, safe = '')}"
    )
    if not isinstance(payload, dict):
        raise error(f"unexpected release payload for {repo}@{tag}")
    return payload


def github_release_assets(ops: ModuleOps, repo: str, tag: str) -> dict[str, str]:
    payload = ops.fetch_json(
        f"https://api.github.com/repos/{repo}/releases/tags/{urllib.parse.quote(tag, safe = '')}"
    )
    if not isinstance(payload, dict):
        raise RuntimeError(f"unexpected release payload for {repo}@{tag}")
    return release_asset_map(payload)


def release_asset_download_url(repo: str, release_tag: str, asset_name: str) -> str:
    """Tag-pinned asset URL on the release-assets CDN (github.com redirect, NOT
    api.github.com, so no 60-req/hour unauthenticated limit)."""
    return (
        f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases/download/"
        f"{urllib.parse.quote(release_tag, safe = '')}/"
        f"{urllib.parse.quote(asset_name, safe = '')}"
    )


# Currency check + resolve ask seconds apart; short TTL so a failure, later run or long-lived importer re-asks.
_DOWNLOAD_HOST_LATEST_TAG_TTL_S = 300.0
_DOWNLOAD_HOST_LATEST_TAG_MEMO: dict[tuple[str, Any], tuple[str, float]] = {}


def download_host_latest_release_tag(ops: ModuleOps, repo: str) -> str | None:
    """Latest release tag from github.com/<repo>/releases/latest via its redirect
    target (no api.github.com call). None on 404 so the caller falls back to the
    API. /releases/latest resolves by created_at/make_latest, which can lag the
    published_at newest the freshness check uses -- acceptable for install."""
    key = (repo, ops._URL_OPENER)
    cached = _DOWNLOAD_HOST_LATEST_TAG_MEMO.get(key)
    if cached is not None and time.monotonic() - cached[1] < _DOWNLOAD_HOST_LATEST_TAG_TTL_S:
        return cached[0]
    tag = _download_host_latest_release_tag_uncached(ops, repo)
    if tag:
        _DOWNLOAD_HOST_LATEST_TAG_MEMO[key] = (tag, time.monotonic())
    return tag


def _download_host_latest_release_tag_uncached(ops: ModuleOps, repo: str) -> str | None:
    url = f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases/latest"
    request = urllib.request.Request(
        url,
        method = "HEAD",
        headers = {"User-Agent": ops.USER_AGENT},
    )
    try:
        with ops._URL_OPENER.open(request, timeout = 30) as response:
            final_url = response.geturl()
    except urllib.error.HTTPError as exc:
        if exc.code == 404:
            return None
        raise
    marker = "/releases/tag/"
    index = final_url.find(marker)
    if index == -1:
        return None
    tag = urllib.parse.unquote(final_url[index + len(marker) :]).strip("/")
    return tag or None


def fetch_download_host_json(ops: ModuleOps, url: str) -> Any:
    data = ops.download_bytes(
        url,
        timeout = 30,
        headers = {"User-Agent": ops.USER_AGENT},
    )
    return json.loads(data.decode("utf-8"))


_WEB_METADATA_MAX_BYTES = 4 * 1024 * 1024

_ATOM_RELEASE_TAG_RE = re.compile(
    r"<link[^>]+href=\"[^\"]*/releases/tag/(?P<tag>[^\"/?#]+)\"", re.IGNORECASE
)

_DOWNLOAD_HREF_RE = re.compile(
    r"href=\"[^\"]*?/releases/download/(?P<tag>[^\"/]+)/(?P<name>[^\"/]+)\"", re.IGNORECASE
)

_CLIPBOARD_TAG_RE = re.compile(r"<clipboard-copy\b(?P<attrs>[^>]*)>", re.IGNORECASE)

_ARIA_DIGEST_FOR_RE = re.compile(
    r"aria-label=\"Copy to clipboard digest for (?P<name>[^\"]+)\"", re.IGNORECASE
)

_ATTR_DIGEST_RE = re.compile(r"value=\"sha256:(?P<hex>[0-9a-f]{64})\"", re.IGNORECASE)


def _fetch_web_metadata(ops: ModuleOps, url: str) -> str:
    """GET a github.com (not api.github.com) metadata page, unauthenticated.

    The web host is outside the anonymous API's hourly budget, which is the whole point
    of the callers below. No token is ever attached.
    """
    data = ops.download_bytes(
        url,
        timeout = 30,
        headers = {"User-Agent": ops.USER_AGENT},
    )
    if len(data) > _WEB_METADATA_MAX_BYTES:
        raise RuntimeError(f"release metadata page at {url} was implausibly large")
    return data.decode("utf-8", "replace")


def web_release_tags(
    ops: ModuleOps,
    repo: str,
    *,
    limit: int = 30,
) -> list[str]:
    """Recent release tags, newest first, from the releases.atom feed; the only tokenless source
    that orders releases, so it restores the older-release walk-back and can name the newest
    nightly."""
    url = f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases.atom"
    body = _fetch_web_metadata(ops, url)
    tags: list[str] = []
    for match in _ATOM_RELEASE_TAG_RE.finditer(body):
        tag = urllib.parse.unquote(match.group("tag")).strip()
        if tag and tag not in tags:
            tags.append(tag)
        if len(tags) >= limit:
            break
    return tags


_PRERELEASE_LABEL_RE = re.compile(r"Label--warning[^>]*>\s*Pre-release\s*<", re.IGNORECASE)


def web_release_prerelease(ops: ModuleOps, repo: str, tag: str) -> bool:
    """Pre-release flag is read from the release page rather than assumed, so the web path never
    picks a release the REST path filters out; drafts are not checked since reaching the page
    proves publication."""
    url = (
        f"https://github.com/{urllib.parse.quote(repo, safe = '/')}/releases/tag/"
        f"{urllib.parse.quote(tag, safe = '')}"
    )
    return _PRERELEASE_LABEL_RE.search(_fetch_web_metadata(ops, url)) is not None


def _web_release_prerelease_or_default(
    ops: ModuleOps, repo: str, tag: str, default: bool | None
) -> bool:
    """Returns the prerelease flag, or default when the page cannot be read, since the assets
    already loaded and one failed request must not drop a usable release."""
    try:
        return web_release_prerelease(ops, repo, tag)
    except Exception as exc:  # noqa: BLE001 - a known answer beats losing the release
        if default is None:
            raise
        ops.log(f"could not read the release label for {repo}@{tag} ({exc}); assuming {default}")
        return default


def web_release_payload(
    ops: ModuleOps,
    repo: str,
    tag: str,
    *,
    prerelease_default: bool | None = None,
) -> dict[str, Any]:
    """An ordinary release payload for <repo>@<tag>, built without api.github.com.

    Shaped like the REST payload on purpose: release_asset_map and release_asset_digests
    keep reading the same fields, so digest enforcement stays authoritative instead of
    being bypassed by a second code path. An asset whose link is not for this exact repo
    and tag, or whose digest is absent or not a sha256, is dropped rather than guessed
    at, since these archives are extracted, chmod 0o755'd and executed.
    """
    quoted_repo = urllib.parse.quote(repo, safe = "/")
    url = (
        f"https://github.com/{quoted_repo}/releases/expanded_assets/"
        f"{urllib.parse.quote(tag, safe = '')}"
    )
    body = _fetch_web_metadata(ops, url)
    published = {
        urllib.parse.unquote(row.group("name")).strip()
        for row in _DOWNLOAD_HREF_RE.finditer(body)
        if urllib.parse.unquote(row.group("tag")).strip() == tag
    }
    # Pair by element, not list position, so a moved row cannot misassign a hash.
    digests: dict[str, str] = {}
    conflicting: set[str] = set()
    for control in _CLIPBOARD_TAG_RE.finditer(body):
        attrs = control.group("attrs")
        labelled = _ARIA_DIGEST_FOR_RE.search(attrs)
        value = _ATTR_DIGEST_RE.search(attrs)
        if labelled is None or value is None:
            continue
        name = labelled.group("name").strip()
        digest = value.group("hex").lower()
        if digests.setdefault(name, digest) != digest:
            conflicting.add(name)
    assets = [
        {
            "name": name,
            "browser_download_url": release_asset_download_url(repo, tag, name),
            "digest": f"sha256:{digests[name]}",
        }
        for name in sorted(published & (digests.keys() - conflicting))
    ]
    if not assets:
        raise RuntimeError(f"no digest-bearing assets were published for {repo}@{tag}")
    return {
        "tag_name": tag,
        "draft": False,
        "prerelease": _web_release_prerelease_or_default(ops, repo, tag, prerelease_default),
        "assets": assets,
    }


# ── Archive extraction (traversal/symlink guarded) ──
def extract_archive(archive_path: Path, destination: Path) -> None:
    def safe_extract_path(base: Path, member_name: str) -> Path:
        normalized = member_name.replace("\\", "/")
        member_path = Path(normalized)
        if member_path.is_absolute():
            raise PrebuiltFallback(f"archive member used an absolute path: {member_name}")

        target = (base / member_path).resolve()
        base_resolved = base.resolve()
        try:
            target.relative_to(base_resolved)
        except ValueError as exc:
            raise PrebuiltFallback(f"archive member escaped destination: {member_name}") from exc
        return target

    def _try_repair_missing_slash(
        member_name: str, link_name: str, archive_names: set[str]
    ) -> str | None:
        """Repairs mangled Mac llama.cpp symlinks (e.g. b9165, b9169) whose linkname drops the
        separator and the basename's leading character; accepts only a unique match, returned
        relative to the member's parent dir because callers join it onto target.parent."""
        if "/" not in member_name or "/" in link_name:
            return None
        top, _, _ = member_name.partition("/")
        if not link_name.startswith(top) or len(link_name) <= len(top):
            return None
        bad_suffix = link_name[len(top) :]
        if not bad_suffix or bad_suffix.startswith("/"):
            return None
        prefix = f"{top}/"
        candidates = [
            name
            for name in archive_names
            if name.startswith(prefix)
            and "/" not in name[len(prefix) :]
            and name[len(prefix) :].endswith(bad_suffix)
        ]
        if len(candidates) != 1:
            return None
        # Strip the top-level dir to avoid a duplicate top/top path.
        return candidates[0][len(prefix) :]

    def safe_link_target(
        base: Path, member_name: str, link_name: str, target: Path, archive_names: set[str]
    ) -> tuple[str, Path]:
        normalized = link_name.replace("\\", "/")
        repaired = _try_repair_missing_slash(member_name, normalized, archive_names)
        if repaired is not None:
            normalized = repaired
        link_path = Path(normalized)
        if link_path.is_absolute():
            raise PrebuiltFallback(
                f"archive link used an absolute target: {member_name} -> {link_name}"
            )
        if not normalized:
            raise PrebuiltFallback(f"archive link used an empty target: {member_name}")

        resolved = (target.parent / link_path).resolve()
        base_resolved = base.resolve()
        try:
            resolved.relative_to(base_resolved)
        except ValueError as exc:
            raise PrebuiltFallback(
                f"archive link escaped destination: {member_name} -> {link_name}"
            ) from exc
        return normalized, resolved

    def extract_zip_safely(source: Path, base: Path) -> None:
        # Local import: every CLI command imports this module.
        import zipfile
        with zipfile.ZipFile(source) as archive:
            for member in archive.infolist():
                target = safe_extract_path(base, member.filename)
                mode = (member.external_attr >> 16) & 0o170000
                if mode == 0o120000:
                    raise PrebuiltFallback(
                        f"zip archive contained a symlink entry: {member.filename}"
                    )
                if member.is_dir():
                    target.mkdir(parents = True, exist_ok = True)
                    continue
                target.parent.mkdir(parents = True, exist_ok = True)
                with archive.open(member, "r") as src, target.open("wb") as dst:
                    shutil.copyfileobj(src, dst)

    def extract_tar_safely(source: Path, base: Path) -> None:
        import tarfile

        pending_links: list[tuple[tarfile.TarInfo, Path]] = []
        archive_names: set[str] = set()
        with tarfile.open(source, "r:gz") as archive:
            for member in archive.getmembers():
                archive_names.add(member.name)
                target = safe_extract_path(base, member.name)
                if member.isdir():
                    target.mkdir(parents = True, exist_ok = True)
                    continue
                if member.islnk() or member.issym():
                    pending_links.append((member, target))
                    continue
                if not member.isfile():
                    raise PrebuiltFallback(
                        f"tar archive contained an unsupported entry: {member.name}"
                    )
                target.parent.mkdir(parents = True, exist_ok = True)
                extracted = archive.extractfile(member)
                if extracted is None:
                    raise PrebuiltFallback(f"tar archive entry could not be read: {member.name}")
                with extracted, target.open("wb") as dst:
                    shutil.copyfileobj(extracted, dst)

        unresolved = list(pending_links)
        while unresolved:
            next_round: list[tuple[tarfile.TarInfo, Path]] = []
            progressed = False
            for member, target in unresolved:
                normalized_link, resolved_target = safe_link_target(
                    base, member.name, member.linkname, target, archive_names
                )
                if not resolved_target.exists() and not resolved_target.is_symlink():
                    next_round.append((member, target))
                    continue
                if resolved_target.is_dir():
                    raise PrebuiltFallback(
                        f"archive link targeted a directory: {member.name} -> {member.linkname}"
                    )

                target.parent.mkdir(parents = True, exist_ok = True)
                if target.exists() or target.is_symlink():
                    target.unlink()

                if member.issym():
                    target.symlink_to(normalized_link)
                else:
                    shutil.copy2(resolved_target, target)
                progressed = True

            if not progressed:
                details = ", ".join(
                    f"{member.name} -> {member.linkname}" for member, _ in next_round
                )
                raise PrebuiltFallback(f"tar archive contained unresolved link entries: {details}")
            unresolved = next_round

    destination.mkdir(parents = True, exist_ok = True)
    if archive_path.name.endswith(".zip"):
        extract_zip_safely(archive_path, destination)
        return
    if archive_path.name.endswith(".tar.gz"):
        extract_tar_safely(archive_path, destination)
        return
    raise PrebuiltFallback(f"unsupported archive format: {archive_path.name}")


def restore_tar_exec_bits(archive_path: Path, destination: Path) -> None:
    """Re-apply tar exec bits after the guarded extraction writes plain files;
    server binaries must stay executable on Unix."""
    if os.name == "nt" or not archive_path.name.endswith(".tar.gz"):
        return
    import tarfile

    with tarfile.open(archive_path, "r:gz") as archive:
        for member in archive.getmembers():
            if not (member.isfile() and member.mode & 0o111):
                continue
            target = destination / Path(member.name.replace("\\", "/"))
            if target.is_file():
                os.chmod(target, target.stat().st_mode | 0o111)


# ── Install lock ──
@contextmanager
def install_lock(lock_path: Path, *, timeout: float | None = None) -> Iterator[None]:
    seconds = INSTALL_LOCK_TIMEOUT_SECONDS if timeout is None else timeout
    lock_path.parent.mkdir(parents = True, exist_ok = True)

    file_lock, file_lock_timeout = filelock_classes()
    if file_lock is None:
        # Fallback lock: exclusive create with our PID for stale-lock detection.
        fd: int | None = None
        deadline = time.monotonic() + seconds
        while True:
            try:
                fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_RDWR)
                try:
                    os.write(fd, f"{os.getpid()}\n".encode())
                    os.fsync(fd)
                except Exception:
                    os.close(fd)
                    fd = None
                    lock_path.unlink(missing_ok = True)
                    raise
                break
            except FileExistsError:
                stale = False
                try:
                    # errors=replace so a garbled lock is treated as corrupt, not retried forever.
                    raw = lock_path.read_text(encoding = "utf-8", errors = "replace").strip()
                except FileNotFoundError:
                    continue
                if not raw:
                    if time.monotonic() >= deadline:
                        raise BusyInstallConflict(
                            f"timed out after {seconds}s waiting for concurrent install lock: {lock_path}"
                        )
                    time.sleep(0.1)
                    continue
                try:
                    holder_pid = int(raw)
                    os.kill(holder_pid, 0)  # signal 0 = existence check
                except ValueError:
                    stale = True  # PID unreadable (corrupted file)
                except ProcessLookupError:
                    stale = True  # holder is dead
                except PermissionError:
                    pass  # alive but owned by another user -- not stale
                if stale:
                    lock_path.unlink(missing_ok = True)
                    continue
                if time.monotonic() >= deadline:
                    raise BusyInstallConflict(
                        f"timed out after {seconds}s waiting for concurrent install lock: {lock_path}"
                    )
                time.sleep(0.5)
        try:
            yield
        finally:
            if fd is not None:
                os.close(fd)
            lock_path.unlink(missing_ok = True)
        return

    try:
        with file_lock(lock_path, timeout = seconds):
            yield
    except file_lock_timeout as exc:
        raise BusyInstallConflict(
            f"timed out after {seconds}s waiting for concurrent install lock: {lock_path}"
        ) from exc


def install_lock_path(install_dir: Path) -> Path:
    return install_dir.parent / f".{install_dir.name}.install.lock"


# ── macOS version parsing ──
def parse_macos_version(value: str | None) -> tuple[int, int] | None:
    """Parses a macOS product version into (major, minor), e.g. 14.7.1, 15.5 or bare 26; None when
    empty or unparseable, so callers defer to runtime validation instead of rejecting every
    prebuilt."""
    if not value:
        return None
    match = re.match(r"\s*(\d+)(?:\.(\d+))?", str(value))
    if not match:
        return None
    return int(match.group(1)), int(match.group(2) or 0)


# ── GPU and CUDA runtime-line selection primitives ──
def normalize_compute_cap(value: Any) -> str | None:
    raw = str(value).strip()
    if not raw:
        return None
    if "." in raw:
        parts = raw.split(".", 1)
        if len(parts) != 2:
            return None
        major, minor = parts
        if not major.isdigit() or not minor.isdigit():
            return None
        return f"{int(major)}{int(minor)}"
    if raw.isdigit():
        return str(int(raw))
    return None


def normalize_compute_caps(compute_caps: Iterable[str]) -> list[str]:
    normalized: list[str] = []
    seen: set[str] = set()
    for raw in compute_caps:
        normalized_value = normalize_compute_cap(raw)
        if normalized_value is None:
            continue
        if normalized_value in seen:
            continue
        seen.add(normalized_value)
        normalized.append(normalized_value)
    normalized.sort(key = int)
    return normalized


def parse_cuda_visible_devices(value: str | None) -> list[str] | None:
    if value is None:
        return None
    raw = value.strip()
    if not raw or raw == "-1":
        return []
    return [token.strip() for token in raw.split(",") if token.strip()]


def supports_explicit_visible_device_matching(visible_devices: list[str] | None) -> bool:
    if not visible_devices:
        return False
    for token in visible_devices:
        lowered = token.lower()
        if token.isdigit() or lowered.startswith("gpu-"):
            continue
        return False
    return True


def select_visible_gpu_rows(
    gpu_rows: Iterable[tuple[str, str, str]], visible_devices: list[str] | None
) -> list[tuple[str, str, str]]:
    rows = list(gpu_rows)
    if visible_devices is None:
        return rows
    if not visible_devices:
        return []

    by_index = {index: (index, uuid, cap) for index, uuid, cap in rows}
    by_uuid = {uuid.lower(): (index, uuid, cap) for index, uuid, cap in rows}
    selected: list[tuple[str, str, str]] = []
    seen_indices: set[str] = set()
    for token in visible_devices:
        row = by_index.get(token)
        if row is None:
            normalized_token = token.lower()
            row = by_uuid.get(normalized_token)
            if row is None and normalized_token.startswith("gpu-"):
                row = by_uuid.get(normalized_token)
            if row is None and not normalized_token.startswith("gpu-"):
                row = by_uuid.get("gpu-" + normalized_token)
        if row is None:
            continue
        index = row[0]
        if index in seen_indices:
            continue
        seen_indices.add(index)
        selected.append(row)
    return selected


def dir_provides_exact_library(directory: str | Path, library: str) -> bool:
    if not library:
        return False
    candidate = Path(directory) / library
    return candidate.exists() and (candidate.is_file() or candidate.is_symlink())


def linux_runtime_dirs_for_required_libraries(
    ops: ModuleOps, required_libraries: Iterable[str]
) -> list[str]:
    required = [library for library in required_libraries if library]
    candidates: list[str | Path] = []

    env_dirs = os.environ.get("CUDA_RUNTIME_LIB_DIR", "")
    if env_dirs:
        candidates.extend(part for part in env_dirs.split(os.pathsep) if part)
    ld_library_path = os.environ.get("LD_LIBRARY_PATH", "")
    if ld_library_path:
        candidates.extend(part for part in ld_library_path.split(os.pathsep) if part)

    cuda_roots: list[Path] = []
    for name in ("CUDA_HOME", "CUDA_PATH", "CUDA_ROOT"):
        value = os.environ.get(name)
        if value:
            cuda_roots.append(Path(value))
    cuda_roots.extend(Path(path) for path in ops.glob_paths("/usr/local/cuda", "/usr/local/cuda-*"))

    for root in cuda_roots:
        candidates.extend(
            [
                root / "lib",
                root / "lib64",
                root / "targets" / "x86_64-linux" / "lib",
            ]
        )

    candidates.extend(
        Path(path)
        for path in ops.glob_paths(
            "/lib",
            "/lib64",
            "/usr/lib",
            "/usr/lib64",
            "/usr/local/lib",
            "/usr/local/lib64",
            "/lib/x86_64-linux-gnu",
            "/usr/lib/x86_64-linux-gnu",
        )
    )
    candidates.extend(
        Path(path) for path in ops.glob_paths("/usr/local/lib/ollama/cuda_v*", "/usr/lib/wsl/lib")
    )
    candidates.extend(Path(path) for path in ops.python_runtime_dirs())
    candidates.extend(Path(path) for path in ops.ldconfig_runtime_dirs(required))

    resolved = ops.dedupe_existing_dirs(candidates)
    if not required:
        return resolved

    matched: list[tuple[int, str]] = []
    for directory in resolved:
        provided = sum(1 for library in required if dir_provides_exact_library(directory, library))
        if provided:
            matched.append((provided, directory))

    matched.sort(key = lambda item: item[0], reverse = True)
    return [directory for _, directory in matched]


def detected_linux_runtime_lines(ops: ModuleOps) -> tuple[list[str], dict[str, list[str]]]:
    """`cuda<major>` lines with a matching libcudart/libcublas file on disk (glob
    match, so a versioned-only file counts), plus the dirs that matched."""
    line_requirements = {
        f"cuda{m}": [f"libcudart.so.{m}", f"libcublas.so.{m}"]
        for m in range(_MAX_PROBE_CUDA_MAJOR, _MIN_CUDA_MAJOR - 1, -1)
    }
    detected: list[str] = []
    runtime_dirs: dict[str, list[str]] = {}
    for line, required in line_requirements.items():
        dirs = ops.linux_runtime_dirs_for_required_libraries(required)
        library_matches: dict[str, list[str]] = {}
        matching_dirs: list[str] = []
        for library in required:
            matched_dirs = [
                directory for directory in dirs if any(Path(directory).glob(f"{library}*"))
            ]
            if not matched_dirs:
                library_matches = {}
                matching_dirs = []
                break
            library_matches[library] = matched_dirs
            for directory in matched_dirs:
                if directory not in matching_dirs:
                    matching_dirs.append(directory)
        if library_matches:
            detected.append(line)
            runtime_dirs[line] = matching_dirs
    return detected, runtime_dirs


def windows_runtime_line_info() -> dict[str, tuple[str, ...]]:
    # Generated per CUDA major, newest first, so a new toolkit needs no code change.
    return {
        f"cuda{m}": (
            f"cudart64_{m}*.dll",
            f"cublas64_{m}*.dll",
            f"cublasLt64_{m}*.dll",
        )
        for m in range(_MAX_PROBE_CUDA_MAJOR, _MIN_CUDA_MAJOR - 1, -1)
    }


def detected_windows_runtime_lines(ops: ModuleOps) -> tuple[list[str], dict[str, list[str]]]:
    dirs = ops.windows_runtime_dirs()
    detected: list[str] = []
    runtime_dirs: dict[str, list[str]] = {}
    for runtime_line, required_patterns in windows_runtime_line_info().items():
        matching_dirs = ops.windows_runtime_dirs_for_patterns(required_patterns, dirs)
        if matching_dirs:
            detected.append(runtime_line)
            runtime_dirs[runtime_line] = matching_dirs
    return detected, runtime_dirs


def driver_below_cuda_prebuilt_floor(host: Any) -> bool:
    """A reported driver too old for any CUDA prebuilt (see _COMPRESSED_FATBIN_MIN_DRIVER)."""
    driver = host.driver_cuda_version
    return bool(driver) and tuple(driver[:2]) < _COMPRESSED_FATBIN_MIN_DRIVER


def cuda_driver_floor_message(host: Any) -> str:
    major, minor = host.driver_cuda_version[:2]
    return (
        f"NVIDIA driver reports CUDA {major}.{minor}, older than the CUDA "
        f"{_COMPRESSED_FATBIN_MIN_DRIVER[0]}.{_COMPRESSED_FATBIN_MIN_DRIVER[1]} the CUDA "
        "llama.cpp prebuilts need (their kernels fail with 'device kernel image is invalid'); "
        "skipping them. Update the NVIDIA driver to R550 or newer (CUDA 12.4+) to use them."
    )


def compatible_linux_runtime_lines(host: Any) -> list[str]:
    if not host.driver_cuda_version:
        return []
    major, _minor = host.driver_cuda_version
    if major < _MIN_CUDA_MAJOR or driver_below_cuda_prebuilt_floor(host):
        return []
    return _cuda_runtime_lines_for_major(major)


def runtime_line_from_cuda_version(cuda_version: str | None) -> str | None:
    if not cuda_version:
        return None
    raw = str(cuda_version).strip()
    if not raw:
        return None
    major, _, _ = raw.partition(".")
    if major == "12":
        return "cuda12"
    if major == "13":
        return "cuda13"
    return None


@dataclass
class CudaRuntimePreference:
    runtime_line: str | None
    selection_log: list[str]


def detect_torch_cuda_runtime_preference(
    host: Any, *, gpu_hidden_by_mask: bool = False
) -> CudaRuntimePreference:
    """The runtime line Torch was built against, so the bundle matches the venv.

    `gpu_hidden_by_mask` is for a caller that already established an NVIDIA GPU hidden by
    CUDA_VISIBLE_DEVICES. Both usual gates answer "no GPU" under that mask, so selection
    would fall back to newest-first and hand a cu12 venv a CUDA 13 bundle. No mask touches
    torch.version.cuda, so it is read without the availability check.
    """
    selection_log: list[str] = []
    if host.is_macos:
        selection_log.append("torch_cuda_preference: skipped on macOS")
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)
    if not ((host.has_usable_nvidia or gpu_hidden_by_mask) and (host.is_linux or host.is_windows)):
        selection_log.append(
            "torch_cuda_preference: skipped because CUDA host prerequisites were not met"
        )
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    try:
        import torch
    except Exception as exc:
        selection_log.append(f"torch_cuda_preference: import failed: {exc}")
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    cuda_version = getattr(getattr(torch, "version", None), "cuda", None)
    if not isinstance(cuda_version, str) or not cuda_version.strip():
        selection_log.append(
            "torch_cuda_preference: torch.version.cuda missing; skipping Torch shortcut"
        )
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    if gpu_hidden_by_mask:
        cuda_available = True
        selection_log.append(
            "torch_cuda_preference: GPU hidden by CUDA_VISIBLE_DEVICES; reading "
            "torch.version.cuda without the availability check"
        )
    else:
        try:
            cuda_available = bool(torch.cuda.is_available())
        except Exception as exc:
            selection_log.append(f"torch_cuda_preference: torch.cuda.is_available() failed: {exc}")
            return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    if not cuda_available:
        selection_log.append(
            "torch_cuda_preference: torch.cuda.is_available() returned False; falling back to normal selection"
        )
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    runtime_line = runtime_line_from_cuda_version(cuda_version)
    if runtime_line is None:
        selection_log.append(
            f"torch_cuda_preference: unsupported torch.version.cuda={cuda_version}; falling back to normal selection"
        )
        return CudaRuntimePreference(runtime_line = None, selection_log = selection_log)

    selection_log.append(
        "torch_cuda_preference: selected runtime_line="
        f"{runtime_line} from torch.version.cuda={cuda_version}"
    )
    return CudaRuntimePreference(runtime_line = runtime_line, selection_log = selection_log)


def artifact_covers_sms(artifact: Any, host_sms: Iterable[str]) -> bool:
    """True when every host SM is in the artifact's supported_sms and within its
    [min_sm, max_sm] range."""
    if not artifact.supported_sms or artifact.min_sm is None or artifact.max_sm is None:
        return False
    supported = {str(value) for value in artifact.supported_sms}
    return all(sm in supported and artifact.min_sm <= int(sm) <= artifact.max_sm for sm in host_sms)


def sm_range(artifact: Any) -> int:
    """SM-coverage span as a sort key (tighter range wins). A bundle with no SM
    metadata gets a max range so it sorts last, never outranking a targeted bundle."""
    if artifact.min_sm is not None and artifact.max_sm is not None:
        return artifact.max_sm - artifact.min_sm
    return 9999


def blackwell_capable_linux_runtime_lines(host_sms: list[str], artifacts: list[Any]) -> list[str]:
    """CUDA runtime lines, highest major first, whose bundles cover every visible host SM; lets a
    Blackwell host prefer a native sm_120 line over torch's reported line, mirroring Windows."""
    lines: set[str] = set()
    for artifact in artifacts:
        line = artifact.runtime_line
        # Skip malformed lines like cuda13.1 rather than crash the sort.
        if not (line and line.startswith("cuda") and line[len("cuda") :].isdigit()):
            continue
        if not artifact.supported_sms or artifact.min_sm is None or artifact.max_sm is None:
            continue
        supported = {str(value) for value in artifact.supported_sms}
        if all(
            sm in supported and artifact.min_sm <= int(sm) <= artifact.max_sm for sm in host_sms
        ):
            lines.add(line)
    return sorted(lines, key = lambda line: int(line[len("cuda") :]), reverse = True)


def host_is_blackwell(host: Any) -> bool:
    caps = normalize_compute_caps(host.compute_caps)
    return bool(caps) and int(caps[-1]) >= _BLACKWELL_MIN_SM


def blackwell_min_toolkit_for_host(host: Any) -> tuple[int, int]:
    """Minimum CUDA toolkit this Blackwell host needs: 12.8 for the family, 12.9
    if any SM is sm_103/sm_121 (no native target before 12.9)."""
    req = _BLACKWELL_MIN_TOOLKIT
    for sm in normalize_compute_caps(host.compute_caps):
        req = max(req, _BLACKWELL_SM_MIN_TOOLKIT.get(int(sm), _BLACKWELL_MIN_TOOLKIT))
    return req


# ════════════════════════════════════════════════════════════════════════════
# ════════════════════════════════════════════════════════════════════════════
def host_platform_tokens(host: Any) -> tuple[str, str]:
    """Default (os, arch) asset tokens; components with their own HostInfo field
    names override this hook."""
    return host.os_token, host.arch_token


# ── Manifest parsing ──
def parse_manifest(ops: ModuleOps, payload: Any, *, label: str) -> dict[str, Any]:
    """Validate a component prebuilt manifest and return it normalized.

    Rejects an unknown schema_version or wrong component. Returns keys:
    schema_version, component, studio_protocol, upstream_tag, source_commit,
    artifacts (list of dicts).
    """
    component = ops.COMPONENT
    if not isinstance(payload, dict):
        raise PrebuiltFallback(f"{label} was not a JSON object")
    validate_schema_version(
        payload, label = label, schema_version = ops.SCHEMA_VERSION, error = PrebuiltFallback
    )
    manifest_component = payload.get("component")
    if manifest_component != component:
        raise PrebuiltFallback(
            f"{label} describes component {manifest_component!r}, expected {component!r}"
        )

    artifacts_raw = payload.get("artifacts")
    if not isinstance(artifacts_raw, list):
        raise PrebuiltFallback(f"{label} omitted an 'artifacts' list")
    artifacts: list[dict[str, Any]] = []
    for index, raw in enumerate(artifacts_raw):
        if not isinstance(raw, dict):
            ops.log(f"{label} artifact[{index}] ignored: not an object")
            continue
        asset = raw.get("asset")
        if not isinstance(asset, str) or not asset:
            ops.log(f"{label} artifact[{index}] ignored: missing asset name")
            continue
        artifacts.append(raw)

    studio_protocol = payload.get("studio_protocol")
    return {
        "schema_version": ops.SCHEMA_VERSION,
        "component": component,
        "studio_protocol": studio_protocol if isinstance(studio_protocol, str) else None,
        "upstream_tag": payload.get("upstream_tag")
        if isinstance(payload.get("upstream_tag"), str)
        else None,
        "source_commit": payload.get("source_commit")
        if isinstance(payload.get("source_commit"), str)
        else None,
        "artifacts": artifacts,
    }


def macos_min_os_ok(ops: ModuleOps, host: Any, min_os: Any) -> bool:
    """True if a macOS artifact requiring `min_os` can load here. The manifest
    labels it `macos-<version>` (e.g. `macos-14.0`); strip that prefix before
    parsing or every entry parses as None and the guard no-ops. Unknown host or
    min_os -> True (defer to runtime validation)."""
    if not isinstance(min_os, str) or not min_os.strip():
        return True
    raw = min_os.strip()
    if raw.lower().startswith("macos-"):
        raw = raw[len("macos-") :]
    required = ops.parse_macos_version(raw)
    if required is None or host.macos_version is None:
        return True
    return host.macos_version >= required


def artifacts_for_host(
    ops: ModuleOps, manifest: dict[str, Any], host: Any, backend: str
) -> list[dict[str, Any]]:
    """Manifest artifacts matching this host os/arch/backend. On macOS, drop any
    whose `min_os` exceeds the host version."""
    os_token, arch_token = ops.host_platform_tokens(host)
    return [
        artifact
        for artifact in manifest.get("artifacts", [])
        if artifact.get("os") == os_token
        and artifact.get("arch") == arch_token
        and artifact.get("backend") == backend
        and (not host.is_macos or ops.macos_min_os_ok(host, artifact.get("min_os")))
    ]


def select_artifact(
    ops: ModuleOps, manifest: dict[str, Any], host: Any, backend: str
) -> dict[str, Any] | None:
    """First manifest artifact matching this host os/arch and backend, or None
    (caller then applies the component's fallback policy). No accelerator
    capability matching here: whisper bundles are slim per os/arch (the paired
    llama.cpp installer already picked SM/gfx-appropriate ggml backends), and
    llama keeps its own selection chain in install_llama_prebuilt.py."""
    candidates = ops.artifacts_for_host(manifest, host, backend)
    return candidates[0] if candidates else None


def select_artifact_with_fallback(
    ops: ModuleOps, manifest: dict[str, Any], host: Any, backend: str
) -> tuple[dict[str, Any], str, bool]:
    """Select the backend artifact, else the descriptor's fallback-backend
    artifact of the same release (whisper: CPU; llama: none, so a GPU miss
    surfaces as "no prebuilt" and the caller does a source build).

    Returns (artifact, effective_backend, used_fallback). Raises PrebuiltFallback
    when neither the requested backend nor the fallback has an asset."""
    os_token, arch_token = ops.host_platform_tokens(host)
    artifact = ops.select_artifact(manifest, host, backend)
    if artifact is not None:
        return artifact, backend, False
    fallback_backend = ops.FALLBACK_BACKEND
    if fallback_backend and backend != fallback_backend:
        fallback_artifact = ops.select_artifact(manifest, host, fallback_backend)
        if fallback_artifact is not None:
            ops.log(
                f"no '{backend}' asset for {os_token}-{arch_token}; "
                f"falling back to the {fallback_backend.upper()} asset of the same release"
            )
            return fallback_artifact, fallback_backend, True
    raise PrebuiltFallback(
        f"no {ops.COMPONENT} prebuilt asset for {os_token}-{arch_token} (backend '{backend}')"
    )


def artifact_coverage(artifact: dict[str, Any]) -> dict[str, Any]:
    """The sm/gfx/min_os coverage recorded for an artifact (marker/fingerprint)."""
    coverage: dict[str, Any] = {}
    for key in ("sm_coverage", "gfx_coverage", "min_os", "sm", "gfx"):
        if key in artifact and artifact.get(key) is not None:
            coverage[key] = artifact.get(key)
    return coverage


# ── Backend resolution ──
def auto_detect_backend(ops: ModuleOps, host: Any) -> str:
    """Host-preferred backend: Apple Silicon -> metal, usable NVIDIA -> cuda,
    AMD gfx -> rocm, otherwise cpu."""
    if host.is_apple_silicon:
        return "metal"
    if host.has_usable_nvidia:
        return "cuda"
    if host.has_rocm:
        return "rocm"
    return "cpu"


def resolve_backend(ops: ModuleOps, host: Any, requested: str | None, *, cpu_fallback: bool) -> str:
    """Resolve the effective backend from --backend / --cpu-fallback and detection."""
    if cpu_fallback:
        return "cpu"
    value = (requested or "auto").strip().lower()
    if value in {"", "auto"}:
        return ops.auto_detect_backend(host)
    if value in ops.SUPPORTED_BACKENDS:
        return value
    raise PrebuiltFallback(
        f"unsupported --backend '{requested}'; choose from auto,{','.join(ops.SUPPORTED_BACKENDS)}"
    )


# ── Release checksum index (trust anchor: the release's own sha256 asset) ──
def valid_sha256(value: Any) -> str | None:
    if not isinstance(value, str):
        return None
    digest = value.strip().lower()
    if digest.startswith("sha256:"):
        digest = digest[len("sha256:") :]
    if len(digest) == 64 and all(c in "0123456789abcdef" for c in digest):
        return digest
    return None


def parse_release_checksums(
    ops: ModuleOps, repo: str, release_tag: str, payload: Any
) -> dict[str, str]:
    """Asset name to sha256 from the release checksum-index asset, the authority for each asset's
    digest; the index must match schema, component and release_tag, and malformed input fails
    closed."""
    label = f"{ops.SHA256_ASSET_NAME} in {repo}@{release_tag}"
    if not isinstance(payload, dict):
        raise PrebuiltFallback(f"{label} was not a JSON object")
    if payload.get("schema_version") != ops.SCHEMA_VERSION:
        raise PrebuiltFallback(f"{label} has an unexpected schema_version")
    if payload.get("component") != ops.COMPONENT:
        raise PrebuiltFallback(f"{label} did not describe {ops.COMPONENT}")
    payload_tag = payload.get("release_tag")
    if not isinstance(payload_tag, str) or not payload_tag:
        raise PrebuiltFallback(f"{label} omitted release_tag")
    if payload_tag != release_tag:
        raise PrebuiltFallback(
            f"{label} release_tag={payload_tag} did not match the resolved release {release_tag}"
        )
    artifacts = payload.get("artifacts")
    if not isinstance(artifacts, dict):
        raise PrebuiltFallback(f"{label} omitted an 'artifacts' map")
    checksums: dict[str, str] = {}
    for asset_name, entry in artifacts.items():
        if not isinstance(asset_name, str) or not asset_name or not isinstance(entry, dict):
            continue
        digest = valid_sha256(entry.get("sha256"))
        if digest is not None:
            checksums[asset_name] = digest
    if not checksums:
        raise PrebuiltFallback(f"{label} carried no usable sha256 entries")
    return checksums


def fetch_release_checksums(ops: ModuleOps, bundle: "ReleaseBundle") -> dict[str, str]:
    """Download + parse the release's checksum-index asset; fails closed if the
    release does not publish it."""
    sha_asset = ops.SHA256_ASSET_NAME
    url = bundle.asset_urls.get(sha_asset)
    if not url:
        raise PrebuiltFallback(
            f"release {bundle.repo}@{bundle.release_tag} has no {sha_asset}; "
            f"cannot verify a download"
        )
    try:
        raw = ops.download_bytes(url, timeout = 30, headers = ops.auth_headers(url))
        payload = json.loads(raw.decode("utf-8"))
    except (urllib.error.URLError, OSError, socket.timeout) as exc:
        raise PrebuiltFallback(
            f"could not fetch {sha_asset} from {bundle.repo}@{bundle.release_tag}: {exc}"
        ) from exc
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise PrebuiltFallback(
            f"{sha_asset} in {bundle.repo}@{bundle.release_tag} was not valid JSON"
        ) from exc
    return ops.parse_release_checksums(bundle.repo, bundle.release_tag, payload)


def expected_sha256_for(
    ops: ModuleOps,
    checksums: dict[str, str],
    asset_name: str,
    *,
    manifest_sha256: str | None = None,
) -> str:
    """The sha256 the archive must match, from the release checksum index; an asset missing from the
    index fails closed, and a manifest sha256 that disagrees means a tampered manifest."""
    digest = checksums.get(asset_name)
    if digest is None:
        raise ReleaseIntegrityError(
            f"{asset_name} is not covered by {ops.SHA256_ASSET_NAME}; "
            f"refusing an unverifiable download"
        )
    embedded = valid_sha256(manifest_sha256)
    if embedded is not None and embedded != digest:
        raise ReleaseIntegrityError(
            f"manifest sha256 for {asset_name} disagrees with {ops.SHA256_ASSET_NAME}; "
            f"refusing a possibly tampered release"
        )
    ops.log(f"verifying {asset_name} against {ops.SHA256_ASSET_NAME} sha256={digest}")
    return digest


# ── Release resolution ──
@dataclass
class ReleaseBundle:
    repo: str
    release_tag: str
    manifest: dict[str, Any]
    asset_urls: dict[str, str]


def fetch_release_bundle(ops: ModuleOps, repo: str, release_tag: str) -> ReleaseBundle:
    """Fetch a fork release, download+validate its manifest, return the bundle.

    The single network seam for API-path release resolution; tests inject a fake
    to exercise selection/install offline. A missing or unreachable release (404,
    rate limit, no network) surfaces as PrebuiltFallback so the caller does a
    source build rather than error out.
    """
    manifest_asset = ops.MANIFEST_ASSET_NAME
    try:
        release = ops.github_release(repo, release_tag)
    except PrebuiltFallback:
        raise
    except (urllib.error.URLError, OSError, socket.timeout) as exc:
        raise PrebuiltFallback(f"could not fetch release {repo}@{release_tag}: {exc}") from exc
    resolved_tag = release.get("tag_name")
    resolved_tag = resolved_tag if isinstance(resolved_tag, str) and resolved_tag else release_tag
    asset_urls = ops.release_asset_map(release)
    manifest_url = asset_urls.get(manifest_asset)
    if not manifest_url:
        raise PrebuiltFallback(
            f"release {repo}@{resolved_tag} has no {manifest_asset}; cannot select a prebuilt"
        )
    try:
        manifest_bytes = ops.download_bytes(
            manifest_url, timeout = 30, headers = ops.auth_headers(manifest_url)
        )
    except (urllib.error.URLError, OSError, socket.timeout) as exc:
        raise PrebuiltFallback(
            f"could not fetch {manifest_asset} from {repo}@{resolved_tag}: {exc}"
        ) from exc
    try:
        manifest_payload = json.loads(manifest_bytes.decode("utf-8"))
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise PrebuiltFallback(
            f"{manifest_asset} in {repo}@{resolved_tag} was not valid JSON"
        ) from exc
    manifest = ops.parse_manifest(
        manifest_payload, label = f"{manifest_asset} in {repo}@{resolved_tag}"
    )
    return ReleaseBundle(
        repo = repo, release_tag = resolved_tag, manifest = manifest, asset_urls = asset_urls
    )


def asset_download_url(ops: ModuleOps, bundle: ReleaseBundle, asset_name: str) -> str:
    url = bundle.asset_urls.get(asset_name)
    if url:
        return url
    # A manifest can list an asset the release JSON omitted.
    return ops.release_asset_download_url(bundle.repo, bundle.release_tag, asset_name)


def resolve_newest_release_tag(ops: ModuleOps, repo: str) -> str:
    """Newest published (non-draft/non-prerelease) release tag for `repo` by
    ``published_at`` -- what the freshness checks use, NOT GitHub's
    ``/releases/latest`` pointer (sorts by commit date, can lag the newest build)."""
    payload = ops.fetch_json(f"https://api.github.com/repos/{repo}/releases?per_page=30")
    if not isinstance(payload, list):
        raise PrebuiltFallback(f"unexpected releases payload for {repo}")
    published = [
        r
        for r in payload
        if isinstance(r, dict)
        and not r.get("draft")
        and not r.get("prerelease")
        and isinstance(r.get("tag_name"), str)
        and r.get("tag_name")
    ]
    if not published:
        raise PrebuiltFallback(f"{repo} has no published prebuilt release yet")
    newest = max(published, key = lambda r: r.get("published_at") or "")
    return newest["tag_name"]


def resolve_release_tag(
    ops: ModuleOps, published_repo: str, *, published_release_tag: str | None
) -> str:
    """The release tag to install: an explicit override, else the newest
    published release resolved at runtime."""
    override = (published_release_tag or "").strip()
    if override:
        return override
    return ops.resolve_newest_release_tag(published_repo)


def resolve_release_via_download_host(
    ops: ModuleOps, repo: str, published_release_tag: str | None
) -> tuple[ReleaseBundle, dict[str, str]] | None:
    """Resolve the release + manifest + checksum index entirely from the download
    host, with zero api.github.com calls. None (caller falls back to the API) on a
    missing/renamed asset, a 404, or a tag mismatch. Fetches the checksum index
    first (an in-progress release can publish it before the manifest)."""
    manifest_asset = ops.MANIFEST_ASSET_NAME
    sha_asset = ops.SHA256_ASSET_NAME
    release_tag = (published_release_tag or "").strip() or ops._download_host_latest_release_tag(
        repo
    )
    if not release_tag:
        return None
    sha_url = ops.release_asset_download_url(repo, release_tag, sha_asset)
    try:
        sha_payload = ops._download_host_json(sha_url)
    except urllib.error.HTTPError as exc:
        if exc.code == 404:
            return None
        raise
    except (
        urllib.error.URLError,
        OSError,
        socket.timeout,
        UnicodeDecodeError,
        json.JSONDecodeError,
    ):
        return None
    try:
        checksums = ops.parse_release_checksums(repo, release_tag, sha_payload)
    except PrebuiltFallback:
        return None  # schema/component/tag mismatch -> let the API path decide
    manifest_url = ops.release_asset_download_url(repo, release_tag, manifest_asset)
    try:
        manifest_payload = ops._download_host_json(manifest_url)
    except urllib.error.HTTPError as exc:
        if exc.code == 404:
            return None
        raise
    except (
        urllib.error.URLError,
        OSError,
        socket.timeout,
        UnicodeDecodeError,
        json.JSONDecodeError,
    ):
        return None
    try:
        manifest = ops.parse_manifest(
            manifest_payload, label = f"{manifest_asset} in {repo}@{release_tag}"
        )
    except PrebuiltFallback:
        return None
    names = {
        str(a.get("asset"))
        for a in manifest.get("artifacts", [])
        if isinstance(a, dict) and a.get("asset")
    }
    names |= {manifest_asset, sha_asset}
    asset_urls = {name: ops.release_asset_download_url(repo, release_tag, name) for name in names}
    bundle = ReleaseBundle(
        repo = repo, release_tag = release_tag, manifest = manifest, asset_urls = asset_urls
    )
    return bundle, checksums


def fetch_release_for_install(
    ops: ModuleOps, repo: str, *, published_release_tag: str | None
) -> tuple[ReleaseBundle, dict[str, str]]:
    """Resolve the release + manifest + checksum index, preferring the download
    host (no api.github.com rate limit) and falling back to the GitHub API. The
    single network seam the install/probe paths use."""
    fast = ops._resolve_release_via_download_host(repo, published_release_tag)
    if fast is not None:
        bundle, checksums = fast
        ops.log(f"resolved {repo}@{bundle.release_tag} via the download host (no GitHub API)")
        return bundle, checksums
    release_tag = ops.resolve_release_tag(repo, published_release_tag = published_release_tag)
    bundle = ops.fetch_release_bundle(repo, release_tag)
    checksums = ops.fetch_release_checksums(bundle)
    return bundle, checksums


# ── Marker and fingerprint ──
def compute_install_fingerprint(
    *,
    published_repo: str,
    release_tag: str,
    upstream_tag: str | None,
    source_commit: str | None,
    asset: str,
    asset_sha256: str,
    backend: str,
    runtime_line: str | None,
    coverage: dict[str, Any],
) -> str:
    payload = {
        "published_repo": published_repo,
        "release_tag": release_tag,
        "upstream_tag": upstream_tag,
        "source_commit": source_commit,
        "asset": asset,
        "asset_sha256": asset_sha256,
        "backend": backend,
        "runtime_line": runtime_line,
        "coverage": coverage,
    }
    return hashlib.sha256(
        json.dumps(payload, sort_keys = True, separators = (",", ":")).encode("utf-8")
    ).hexdigest()


@dataclass(frozen = True)
class InstallSelection:
    """The identity of a chosen prebuilt: everything the marker/fingerprint record."""

    published_repo: str
    release_tag: str
    upstream_tag: str | None
    source_commit: str | None
    asset: str
    asset_sha256: str
    backend: str
    runtime_line: str | None
    coverage: dict[str, Any]
    studio_protocol: str | None
    # Slim pairing identity; None for fat installs, never fingerprinted.
    install_kind: str | None = None
    paired_llama_tag: str | None = None
    linked_from: str | None = None
    # Verified by the sidecar launch guard instead of hardcoded names.
    linked_libraries: tuple[str, ...] | None = None
    runtime_wiring_version: int | None = None
    linked_runtime_directories: tuple[str, ...] | None = None
    # Never fingerprinted.
    walk_back: "WalkBack | None" = None
    # Recorded so keep decisions need not parse asset names. Outside the fingerprint.
    platform_os: str | None = None
    platform_arch: str | None = None

    def fingerprint(self) -> str:
        return compute_install_fingerprint(
            published_repo = self.published_repo,
            release_tag = self.release_tag,
            upstream_tag = self.upstream_tag,
            source_commit = self.source_commit,
            asset = self.asset,
            asset_sha256 = self.asset_sha256,
            backend = self.backend,
            runtime_line = self.runtime_line,
            coverage = self.coverage,
        )


@dataclass(frozen = True)
class WalkBack:
    """A macOS release walk-back: the newest published release the planner skipped
    because the host was below its OS floor, and the host version that decided it.

    Recorded on the marker as walk_back and walked_back_on_macos, outside the
    fingerprint (it describes the choice, not the bundle). The marker-only re-check
    holds an install current while BOTH still stand: the newest published release is
    the one skipped, and the host is the macOS version that skipped it. A newer release
    or an OS upgrade takes the full path, which re-decides the walk-back.
    """

    release_tag: str
    macos_version: str

    def marker_fields(self) -> dict[str, str]:
        return {
            "walked_back_from": self.release_tag,
            "walked_back_on_macos": self.macos_version,
        }


WALK_BACK_KEYS = ("walked_back_from", "walked_back_on_macos")


def macos_version_label(host: Any) -> str | None:
    """The host's macOS version as recorded beside a walk-back ("14.7"); None off
    macOS or when the version is unknown."""
    if not getattr(host, "is_macos", False):
        return None
    version = getattr(host, "macos_version", None)
    if not version:
        return None
    return ".".join(str(part) for part in version)


def walk_back_for(host: Any, skipped_release_tag: str | None) -> WalkBack | None:
    """Walk-back to record when the planner settled below skipped_release_tag on this host; None
    without a skipped release, off macOS, or when the host version cannot be compared."""
    if not skipped_release_tag:
        return None
    label = macos_version_label(host)
    if label is None:
        return None
    return WalkBack(release_tag = skipped_release_tag, macos_version = label)


def marker_walk_back(marker: dict[str, Any]) -> WalkBack | None:
    """The walk-back a marker records, or None when it records none or only half of
    one (a marker written before the host version was kept beside the tag)."""
    release_tag = marker.get("walked_back_from")
    macos_version = marker.get("walked_back_on_macos")
    if not (isinstance(release_tag, str) and release_tag):
        return None
    if not (isinstance(macos_version, str) and macos_version):
        return None
    return WalkBack(release_tag = release_tag, macos_version = macos_version)


def walk_back_stands(marker: dict[str, Any], host: Any, expected_release: str | None) -> bool:
    """Whether the marker's walk-back still explains why expected_release, the newest published
    release, is not installed: same skipped release and same host macOS version."""
    recorded = marker_walk_back(marker)
    if recorded is None or not expected_release:
        return False
    return (
        recorded.release_tag == expected_release
        and recorded.macos_version == macos_version_label(host)
    )


def walk_back_patch(marker: dict[str, Any], walk_back: WalkBack | None) -> dict[str, Any]:
    """The marker keys a reused install must take from this run's walk-back: both
    fields when the plan walked back and the marker says otherwise, None for each
    one present when the plan no longer walks back."""
    if walk_back is None:
        return {key: None for key in WALK_BACK_KEYS if marker.get(key) is not None}
    return {
        key: value for key, value in walk_back.marker_fields().items() if marker.get(key) != value
    }


def selection_from_artifact(
    ops: ModuleOps,
    *,
    published_repo: str,
    release_tag: str,
    manifest: dict[str, Any],
    artifact: dict[str, Any],
    backend: str,
    asset_sha256: str,
) -> InstallSelection:
    return InstallSelection(
        published_repo = published_repo,
        release_tag = release_tag,
        upstream_tag = manifest.get("upstream_tag"),
        source_commit = manifest.get("source_commit"),
        asset = str(artifact.get("asset")),
        asset_sha256 = asset_sha256,
        backend = backend,
        runtime_line = artifact.get("runtime_line")
        if isinstance(artifact.get("runtime_line"), str)
        else None,
        coverage = ops.artifact_coverage(artifact),
        studio_protocol = manifest.get("studio_protocol"),
        platform_os = artifact.get("os") if isinstance(artifact.get("os"), str) else None,
        platform_arch = artifact.get("arch") if isinstance(artifact.get("arch"), str) else None,
    )


def metadata_path(ops: ModuleOps, install_dir: Path) -> Path:
    return install_dir / ops.METADATA_FILENAME


def write_prebuilt_metadata(ops: ModuleOps, install_dir: Path, selection: InstallSelection) -> None:
    coverage = selection.coverage
    payload = {
        "schema_version": ops.SCHEMA_VERSION,
        "component": ops.COMPONENT,
        "published_repo": selection.published_repo,
        "release_tag": selection.release_tag,
        "upstream_tag": selection.upstream_tag,
        "source_commit": selection.source_commit,
        "asset": selection.asset,
        "asset_sha256": selection.asset_sha256,
        "backend": selection.backend,
        "runtime_line": selection.runtime_line,
        "sm_coverage": coverage.get("sm_coverage") or coverage.get("sm"),
        "gfx_coverage": coverage.get("gfx_coverage") or coverage.get("gfx"),
        "min_os": coverage.get("min_os"),
        "studio_protocol": selection.studio_protocol,
        "install_fingerprint": selection.fingerprint(),
        # Lets a later run tell a whole marker from an edited one.
        "fingerprint_coverage": coverage,
        "installed_at_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
    }
    if selection.walk_back is not None:
        payload.update(selection.walk_back.marker_fields())
    if selection.platform_os and selection.platform_arch:
        payload["os"] = selection.platform_os
        payload["arch"] = selection.platform_arch
    if selection.install_kind == "slim":
        # Fat markers keep the legacy payload exactly.
        payload["install_kind"] = "slim"
        payload["paired_llama_tag"] = selection.paired_llama_tag
        payload["linked_from"] = selection.linked_from
        paired_tree = getattr(ops, "installed_paired_runtime_tree", None)
        paired_tree = paired_tree() if callable(paired_tree) else None
        if isinstance(paired_tree, str) and paired_tree:
            payload["paired_llama_ggml_tree"] = paired_tree
        # One release ships a bundle per gfx target, so the tree id alone is not enough.
        paired_id = getattr(ops, "installed_paired_runtime_id", None)
        paired_id = paired_id() if callable(paired_id) else None
        if isinstance(paired_id, str) and paired_id:
            payload["paired_llama_runtime_id"] = paired_id
        if selection.linked_libraries is not None:
            payload["linked_libraries"] = list(selection.linked_libraries)
        if selection.runtime_wiring_version is not None:
            payload["runtime_wiring_version"] = selection.runtime_wiring_version
        if selection.linked_runtime_directories is not None:
            payload["linked_runtime_directories"] = list(selection.linked_runtime_directories)
    # Written last so it covers the wiring above.
    records = getattr(ops, "runtime_file_records", None)
    records = records(install_dir, selection) if callable(records) else None
    if records:
        payload["runtime_files"] = records
    ops.metadata_path(install_dir).write_text(
        json.dumps(payload, indent = 2) + "\n", encoding = "utf-8"
    )


def marker_install_fingerprint(metadata: dict[str, Any]) -> str | None:
    """The fingerprint recomputed from the marker's own recorded fields.

    Self-consistency, not a comparison against a fresh plan: equal to the recorded
    install_fingerprint only when every field it was computed from is still the one
    written with it, which is what lets a no-network check trust the release_tag it
    reads. None for a marker that predates fingerprint_coverage, which then takes the
    full path once and is settled there (_backfill_fingerprint_inputs).
    """
    coverage = metadata.get("fingerprint_coverage")
    if not isinstance(coverage, dict):
        return None
    try:
        return compute_install_fingerprint(
            published_repo = str(metadata.get("published_repo")),
            release_tag = str(metadata.get("release_tag")),
            upstream_tag = metadata.get("upstream_tag"),
            source_commit = metadata.get("source_commit"),
            asset = str(metadata.get("asset")),
            asset_sha256 = str(metadata.get("asset_sha256")),
            backend = str(metadata.get("backend")),
            runtime_line = metadata.get("runtime_line"),
            coverage = coverage,
        )
    except (TypeError, ValueError):
        return None


def _kept_marker_patch(
    ops: ModuleOps, install_dir: Path, selection: InstallSelection
) -> dict[str, Any] | None:
    """What a kept install's marker still has to take from this run's selection.

    fingerprint_coverage and the platform on a marker written before those keys
    existed, and the walk-back this run's plan made (or retired). None when nothing
    is owed, or when the component has no marker readers (optional, like the settle
    hooks).
    """
    load = getattr(ops, "load_prebuilt_metadata", None)
    if load is None or getattr(ops, "metadata_path", None) is None:
        return None
    metadata = load(install_dir)
    if not metadata:
        return None
    patch: dict[str, Any] = {}
    if not isinstance(metadata.get("fingerprint_coverage"), dict):
        patch["fingerprint_coverage"] = selection.coverage
    patch.update(walk_back_patch(metadata, selection.walk_back))
    if (
        selection.platform_os
        and selection.platform_arch
        and not (isinstance(metadata.get("os"), str) and isinstance(metadata.get("arch"), str))
    ):
        patch["os"] = selection.platform_os
        patch["arch"] = selection.platform_arch
    return patch or None


def _kept_marker_needs_settle(
    ops: ModuleOps, install_dir: Path, selection: InstallSelection
) -> bool:
    return _kept_marker_patch(ops, install_dir, selection) is not None


def _backfill_fingerprint_inputs(
    ops: ModuleOps, install_dir: Path, selection: InstallSelection
) -> None:
    """Catch a kept marker up to this run: fingerprint_coverage and the platform where
    the marker predates those keys, and the walk-back the plan made or retired.

    Only for a marker whose fingerprint this run's selection reproduces, so the
    coverage written is the one it was computed from; anything else is left for the
    install path to rewrite whole.
    """
    patch = _kept_marker_patch(ops, install_dir, selection)
    if not patch:
        return
    metadata = ops.load_prebuilt_metadata(install_dir)
    # Another installer may have swapped the tree; it wrote its own marker.
    if not metadata:
        return
    if metadata.get("install_fingerprint") != selection.fingerprint():
        return
    for key, value in patch.items():
        if value is None:
            metadata.pop(key, None)
        else:
            metadata[key] = value
    # Temp-and-replace so a failed write leaves the live marker valid.
    write_live_marker(ops.metadata_path(install_dir), metadata)


def load_prebuilt_metadata(ops: ModuleOps, install_dir: Path) -> dict[str, Any] | None:
    path = ops.metadata_path(install_dir)
    if not path.is_file():
        return None
    try:
        payload = json.loads(path.read_text(encoding = "utf-8"))
    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
        return None
    return payload if isinstance(payload, dict) else None


def existing_install_matches(
    ops: ModuleOps, install_dir: Path, host: Any, selection: InstallSelection
) -> bool:
    """True iff the marker records this exact selection and the server binary is on disk."""
    metadata = ops.load_prebuilt_metadata(install_dir)
    if metadata is None:
        return False
    if not ops.installed_server_path(install_dir, host).is_file():
        return False
    recorded = metadata.get("install_fingerprint")
    if not isinstance(recorded, str) or recorded != selection.fingerprint():
        return False
    ops.log(
        f"existing {ops.COMPONENT} install already matches {selection.release_tag} "
        f"({selection.backend}); nothing to do"
    )
    return True


# ── Install tree assembly and staged activation ──
def locate_server_in_tree(ops: ModuleOps, root: Path, host: Any) -> Path:
    name = ops.server_binary_name(host)
    matches = sorted(root.rglob(name))
    if not matches:
        raise PrebuiltFallback(f"archive did not contain a {name} binary")
    return matches[0]


def assemble_install_tree(ops: ModuleOps, bundle_root: Path, staged_root: Path, host: Any) -> Path:
    """Lay out staged_root as a full install in the runtime bin dir: co-locate everything beside the
    server (shared libs, backend kernel subdirs, license) so RUNPATH=$ORIGIN resolves its libs."""
    bin_dir = ops.runtime_bin_dir(staged_root, host)
    bin_dir.mkdir(parents = True, exist_ok = True)
    for entry in sorted(bundle_root.iterdir()):
        dest = bin_dir / entry.name
        if entry.is_dir() and not entry.is_symlink():
            shutil.copytree(entry, dest, symlinks = True)
        else:
            shutil.copy2(entry, dest, follow_symlinks = False)
    server = bin_dir / ops.server_binary_name(host)
    if not server.exists():
        raise PrebuiltFallback(f"staged install is missing the {ops.COMPONENT} server binary")
    if not host.is_windows:
        os.chmod(server, server.stat().st_mode | 0o111)
    return server


def swap_into_place(staged_root: Path, install_dir: Path) -> None:
    """Atomically replace install_dir with staged_root (same filesystem), with rollback."""
    install_dir.parent.mkdir(parents = True, exist_ok = True)
    backup: Path | None = None
    try:
        if install_dir.exists():
            backup = install_dir.parent / f".{install_dir.name}.old-{os.getpid()}"
            os.replace(install_dir, backup)
        os.replace(staged_root, install_dir)
    except OSError as exc:
        restored = False
        if backup is not None and backup.exists() and not install_dir.exists():
            try:
                os.replace(backup, install_dir)
                restored = True
            except OSError as rollback_exc:
                raise PrebuiltFallback(
                    "prebuilt activation failed and the previous install could not be restored "
                    f"({exc}; rollback: {rollback_exc})"
                ) from rollback_exc
        if is_busy_lock_error(exc):
            detail = "; restored the previous install" if restored else ""
            raise BusyInstallConflict(
                f"the existing install appears to still be in use{detail} ({exc})"
            ) from exc
        raise
    if backup is not None:
        shutil.rmtree(backup, ignore_errors = True)


def validate_staged_server(ops: ModuleOps, staged_root: Path, host: Any) -> None:
    """Optional pre-activate smoke test, gated off by default (the component's
    _RUN_STAGED_PREBUILT_VALIDATION switch)."""
    if not ops._RUN_STAGED_PREBUILT_VALIDATION:
        return
    server = ops.installed_server_path(staged_root, host)
    env = os.environ.copy()
    bin_dir = str(ops.runtime_bin_dir(staged_root, host))
    for var in ("LD_LIBRARY_PATH", "DYLD_LIBRARY_PATH"):
        env[var] = bin_dir + (os.pathsep + env[var] if env.get(var) else "")
    try:
        result = subprocess.run(
            [str(server), "--help"],
            capture_output = True,
            text = True,
            encoding = "utf-8",
            errors = "replace",
            timeout = 60,
            env = env,
            **ops.windows_hidden_subprocess_kwargs(),
        )
    except (OSError, subprocess.SubprocessError) as exc:
        raise PrebuiltFallback(f"staged {ops.COMPONENT} server failed to launch: {exc}") from exc
    if result.returncode != 0:
        raise PrebuiltFallback(
            f"staged {ops.COMPONENT} server --help exited {result.returncode}: "
            f"{result.stderr.strip()}"
        )


def windows_hidden_subprocess_kwargs() -> dict[str, object]:
    """Return Windows-only subprocess kwargs that suppress console windows."""
    if sys.platform != "win32":
        return {}

    kwargs: dict[str, object] = {}
    create_no_window = getattr(subprocess, "CREATE_NO_WINDOW", 0)
    if create_no_window:
        kwargs["creationflags"] = create_no_window

    startupinfo_factory = getattr(subprocess, "STARTUPINFO", None)
    startf_use_showwindow = getattr(subprocess, "STARTF_USESHOWWINDOW", 0)
    sw_hide = getattr(subprocess, "SW_HIDE", 0)
    if startupinfo_factory is not None and startf_use_showwindow:
        startupinfo = startupinfo_factory()
        startupinfo.dwFlags |= startf_use_showwindow
        startupinfo.wShowWindow = sw_hide
        kwargs["startupinfo"] = startupinfo

    return kwargs


def install_from_bundle(
    ops: ModuleOps, install_dir: Path, host: Any, bundle: ReleaseBundle, selection: InstallSelection
) -> None:
    staging_root = install_dir.parent / ops.INSTALL_STAGING_ROOT_NAME
    staging_root.mkdir(parents = True, exist_ok = True)
    staging = make_staging_dir(staging_root, f"{install_dir.name}.staging-")
    try:
        archive_path = staging / selection.asset
        url = ops.asset_download_url(bundle, selection.asset)
        ops.log(f"downloading {url}")
        ops.download_file_verified(
            url, archive_path, expected_sha256 = selection.asset_sha256, label = selection.asset
        )
        extract_dir = staging / "extracted"
        ops.extract_archive(archive_path, extract_dir)

        server = ops.locate_server_in_tree(extract_dir, host)
        bundle_root = server.parent

        staged_root = staging / "staged"
        ops.assemble_install_tree(bundle_root, staged_root, host)
        # Wire the slim runtime before staged validation; the returned selection supersedes the input.
        updated = ops.prepare_runtime_payload(staged_root, host, selection)
        if updated is not None:
            selection = updated
        ops.validate_staged_server(staged_root, host)
        ops.write_prebuilt_metadata(staged_root, selection)
        ops._swap_into_place(staged_root, install_dir)
    finally:
        shutil.rmtree(staging, ignore_errors = True)
        try:
            staging_root.rmdir()
        except OSError:
            pass


def plan_selection(
    ops: ModuleOps,
    host: Any,
    bundle: ReleaseBundle,
    *,
    published_repo: str,
    backend: str,
    checksums: dict[str, str],
) -> InstallSelection:
    """Choose an artifact (with the component's fallback policy) and resolve its
    trusted sha256 from the release checksum index."""
    artifact, effective_backend, _used_fallback = ops.select_artifact_with_fallback(
        bundle.manifest, host, backend
    )
    asset = str(artifact.get("asset"))
    manifest_sha256 = artifact.get("sha256") if isinstance(artifact.get("sha256"), str) else None
    expected_sha = ops.expected_sha256_for(
        checksums,
        asset,
        manifest_sha256 = manifest_sha256,
    )
    return ops.selection_from_artifact(
        published_repo = published_repo,
        release_tag = bundle.release_tag,
        manifest = bundle.manifest,
        artifact = artifact,
        backend = effective_backend,
        asset_sha256 = expected_sha,
    )


def install_prebuilt(
    ops: ModuleOps,
    install_dir: Path,
    *,
    published_repo: str,
    published_release_tag: str | None = None,
    backend: str | None = "auto",
    cpu_fallback: bool = False,
    force: bool = False,
    host: Any = None,
) -> int:
    if host is None:
        host = ops.detect_host()
    effective_backend = ops.resolve_backend(host, backend, cpu_fallback = cpu_fallback)
    os_token, arch_token = ops.host_platform_tokens(host)
    ops.log(
        f"target {ops.COMPONENT} from {published_repo} "
        f"({os_token}-{arch_token}, backend {effective_backend})"
    )

    bundle, checksums = ops.fetch_release_for_install(
        published_repo, published_release_tag = published_release_tag
    )
    selection = ops.plan_selection(
        host,
        bundle,
        published_repo = published_repo,
        backend = effective_backend,
        checksums = checksums,
    )

    return install_selected_prebuilt(
        ops,
        install_dir,
        host = host,
        bundle = bundle,
        selection = selection,
        force = force,
    )


def install_selected_prebuilt(
    ops: ModuleOps,
    install_dir: Path,
    *,
    host: Any,
    bundle: ReleaseBundle,
    selection: InstallSelection,
    force: bool,
) -> int:
    """Validate and activate an already selected release plan.

    Components that need to examine more than one published release can keep
    release selection component-specific while sharing the lock, idempotency,
    atomic activation, and post-install verification path.
    """

    if not force and ops.existing_install_matches(install_dir, host, selection):
        if _settle_kept_install(ops, install_dir, host, selection, locked = False):
            return 0

    with ops.install_lock(ops.install_lock_path(install_dir)):
        # Re-check under the lock: a concurrent run may have just finished.
        if not force and ops.existing_install_matches(install_dir, host, selection):
            _settle_kept_install(ops, install_dir, host, selection, locked = True)
            return 0
        ops._install_from_bundle(install_dir, host, bundle, selection)

    server = ops.installed_server_path(install_dir, host)
    if not server.is_file():
        raise PrebuiltFallback(f"post-install verification failed: {server} is missing")
    ops.log(
        f"installed {ops.COMPONENT} {bundle.release_tag} " f"({selection.backend}) at {install_dir}"
    )
    return 0


def _settle_kept_install(
    ops: ModuleOps, install_dir: Path, host: Any, selection: InstallSelection, *, locked: bool
) -> bool:
    """Catches up a kept install's marker under the install lock, since an unlocked rewrite can race
    a concurrent swap; optional per component; returns False only when the locked re-check finds
    another install; never raises."""
    settle = getattr(ops, "settle_kept_install", None)
    needs_settling = getattr(ops, "kept_install_needs_settling", None)
    try:
        if locked:
            _backfill_fingerprint_inputs(ops, install_dir, selection)
            if settle is not None:
                settle(install_dir)
            return True
        needs = _kept_marker_needs_settle(ops, install_dir, selection) or (
            needs_settling is not None and needs_settling(install_dir)
        )
        if not needs:
            return True
        with ops.install_lock(
            ops.install_lock_path(install_dir), timeout = SETTLE_LOCK_TIMEOUT_SECONDS
        ):
            if ops.existing_install_matches(install_dir, host, selection):
                _backfill_fingerprint_inputs(ops, install_dir, selection)
                if settle is not None:
                    settle(install_dir)
                return True
    except Exception as exc:  # noqa: BLE001 - a metadata catch-up must never fail a kept install
        ops.log(f"kept {ops.COMPONENT} install not settled: {exc}")
        return True
    ops.log(f"kept {ops.COMPONENT} install changed under the lock; re-validating")
    return False


def resolve_prebuilt(
    ops: ModuleOps,
    host: Any,
    *,
    published_repo: str,
    published_release_tag: str | None,
    backend: str | None,
    cpu_fallback: bool,
) -> dict[str, Any]:
    """Host-aware "is a prebuilt available" probe. No archive download."""
    effective_backend = ops.resolve_backend(host, backend, cpu_fallback = cpu_fallback)
    try:
        bundle, _checksums = ops.fetch_release_for_install(
            published_repo, published_release_tag = published_release_tag
        )
        artifact, resolved_backend, used_fallback = ops.select_artifact_with_fallback(
            bundle.manifest, host, effective_backend
        )
    except PrebuiltFallback:
        return {"prebuilt_available": False, "repo": published_repo}
    os_token, arch_token = ops.host_platform_tokens(host)
    payload = {
        "prebuilt_available": True,
        "repo": published_repo,
        "release_tag": bundle.release_tag,
        "upstream_tag": bundle.manifest.get("upstream_tag"),
        "backend": resolved_backend,
        "requested_backend": effective_backend,
        "cpu_fallback": used_fallback,
        "asset": str(artifact.get("asset")),
        "os": os_token,
        "arch": arch_token,
        "runtime_line": artifact.get("runtime_line"),
    }
    # The JSON emitter sorts keys, so appended fields cannot perturb legacy order.
    payload.update(ops.resolver_payload_extra(artifact))
    return payload


def prepare_runtime_payload(staged_root: Path, host: Any, selection: InstallSelection) -> Any:
    """Post-assemble hook; the core stages nothing extra. Components override it
    to wire external runtime files into the staged bin dir (whisper slim hardlinks
    the llama install's ggml libraries) before validation, and may return an
    updated InstallSelection for the marker to record instead."""
    return None


def resolver_payload_extra(artifact: dict[str, Any]) -> dict[str, Any]:
    """Additive --resolve-prebuilt payload fields; the core adds none."""
    return {}


def installed_server_path(ops: ModuleOps, install_dir: Path, host: Any) -> Path:
    return ops.runtime_bin_dir(install_dir, host) / ops.server_binary_name(host)


_download_host_latest_release_tag = download_host_latest_release_tag
_download_host_json = fetch_download_host_json
_resolve_release_via_download_host = resolve_release_via_download_host
_install_from_bundle = install_from_bundle
_swap_into_place = swap_into_place


def emit_resolver_output(payload: dict[str, Any], *, output_format: str) -> None:
    if output_format == "json":
        print(json.dumps(payload, sort_keys = True))
        return
    if "asset" in payload and payload.get("prebuilt_available"):
        print(payload["asset"])
        return
    print(json.dumps(payload, sort_keys = True))