ixt-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{ixt_cli-0.9.0 → ixt_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ixt-cli
-Version: 0.9.0
+Version: 0.10.0
 Summary: Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation
 Project-URL: Homepage, https://gitlab.com/pytgaen-group/ixt
 Project-URL: Repository, https://gitlab.com/pytgaen-group/ixt.git
@@ -51,10 +51,10 @@ Description-Content-Type: text/markdown
 *Zero third-party deps. Zero system pollution. One command, any ecosystem.*
 
 - **Day-one GitHub releases** — install a tool the day it ships, without
-  waiting for a formula, registry entry, or plugin.
+    waiting for a formula, registry entry, or plugin.
 - **No system runtime needed** — ixt is pure Python stdlib; `uv` and `bun` are
-  bootstrapped on first use, so the host does not need Node, npm, or a package
-  manager pre-installed.
+    bootstrapped on first use, so the host does not need Node, npm, or a package
+    manager pre-installed.
 
 ```bash
 ixt tool install ruff                      # Python (PyPI)
@@ -202,40 +202,44 @@ ixt tool apply --locked --strict
 
 `--locked` replays the exact lock instead of resolving newer versions.
 `--strict` fails before changing the machine if `ixt.toml` and `ixt.lock`
-diverge.
+diverge. The strict preflight is local: it checks the manifest fingerprint,
+declared policy, version constraints, and locked binary metadata without
+contacting PyPI, npm, GitHub, or GitLab. Run `ixt lock write` when you want to
+resolve upstream again and refresh the lock.
 
 ## 🧰 Commands
 
 | Command                                        | Description                                                           |
 | ---------------------------------------------- | --------------------------------------------------------------------- |
-| `ixt tool add <pkg>`                                | Add a tool to ixt.toml without installing                             |
-| `ixt tool install <pkg>`                            | Install a tool in isolation                                           |
-| `ixt tool install <pkg> --bare`                     | Install the env without exposing any binary                           |
-| `ixt tool uninstall <pkg>`                          | Remove a tool                                                         |
-| `ixt tool list`                                     | List installed tools                                                  |
-| `ixt tool info <pkg>`                               | Show tool details                                                     |
-| `ixt tool upgrade <pkg>`                            | Upgrade a tool                                                        |
-| `ixt tool upgrade --all`                            | Upgrade all tools                                                     |
-| `ixt tool apply`                                    | Sync tools from declarative config                                    |
-| `ixt tool apply --locked --strict`                   | Sync using exact versions and assets from ixt.lock                    |
-| `ixt tool export`                             | Export installed tools as ixt.toml (stdout), preserves install intent |
-| `ixt lock write`                              | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                              | Fail if ixt.lock is missing or stale                                  |
-| `ixt lock diff`                               | Show semantic differences between ixt.toml and ixt.lock               |
+| `ixt tool add <pkg>`                           | Add a tool to ixt.toml without installing                             |
+| `ixt tool install <pkg>`                       | Install a tool in isolation                                           |
+| `ixt tool install <pkg> --bare`                | Install the env without exposing any binary                           |
+| `ixt tool uninstall <pkg>`                     | Remove a tool                                                         |
+| `ixt tool list`                                | List installed tools                                                  |
+| `ixt tool info <pkg>`                          | Show tool details                                                     |
+| `ixt tool upgrade <pkg>`                       | Upgrade a tool                                                        |
+| `ixt tool upgrade --all`                       | Upgrade all tools                                                     |
+| `ixt tool apply`                               | Sync tools from declarative config                                    |
+| `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
+| `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
+| `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
+| `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
-| `ixt tool config <pkg> expose <rules...>`           | Change exposed binaries                                               |
-| `ixt tool config <pkg> inject <dep>`                | Inject a package into the tool's env                                  |
-| `ixt tool config <pkg> uninject <dep>`              | Remove an injected package                                            |
-| `ixt tool config __all__ expose <rules...>`         | Re-expose every installed tool                                        |
-| `ixt tool shell <pkg>`                              | Open a subshell in tool's env                                         |
-| `ixt tool where <pkg>`                              | Print the tool env path                                               |
+| `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
+| `ixt tool config <pkg> inject <dep>`           | Inject a package into the tool's env                                  |
+| `ixt tool config <pkg> uninject <dep>`         | Remove an injected package                                            |
+| `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
+| `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
+| `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |
 | `ixt cache prune`                              | Keep current + previous indexed download artifacts per repository     |
 | `ixt cache clear {downloads,metadata,tmp,all}` | Wipe cache(s); never touches installed tools                          |
-| `ixt runtime info`                            | Show ixt-managed runtime state                                        |
-| `ixt runtime prune [--all]`                   | Remove unused or all ixt-managed runtimes                             |
+| `ixt runtime info`                             | Show ixt-managed runtime state                                        |
+| `ixt runtime prune [--all]`                    | Remove unused or all ixt-managed runtimes                             |
 | `ixt setup path`                               | Add `$IXT_HOME/installed/bin` to PATH                                 |
 | `ixt setup completions --shell zsh`            | Print shell completion code for ixt                                   |
 
@@ -285,7 +289,7 @@ ixt is **not** a runtime version manager (mise, proto, asdf cover that). It mana
 git clone https://gitlab.com/pytgaen-group/ixt.git && cd ixt
 uv sync --group dev
 
-uv run pytest                 # test suite
+uv run pytest                 # hermetic unit suite
 uv run ruff check src/ tests/ # lint
 uv run ruff format src/ tests/ # format
 ```

{ixt_cli-0.9.0 → ixt_cli-0.10.0}/README.md

@@ -22,10 +22,10 @@
 *Zero third-party deps. Zero system pollution. One command, any ecosystem.*
 
 - **Day-one GitHub releases** — install a tool the day it ships, without
-  waiting for a formula, registry entry, or plugin.
+    waiting for a formula, registry entry, or plugin.
 - **No system runtime needed** — ixt is pure Python stdlib; `uv` and `bun` are
-  bootstrapped on first use, so the host does not need Node, npm, or a package
-  manager pre-installed.
+    bootstrapped on first use, so the host does not need Node, npm, or a package
+    manager pre-installed.
 
 ```bash
 ixt tool install ruff                      # Python (PyPI)
@@ -173,40 +173,44 @@ ixt tool apply --locked --strict
 
 `--locked` replays the exact lock instead of resolving newer versions.
 `--strict` fails before changing the machine if `ixt.toml` and `ixt.lock`
-diverge.
+diverge. The strict preflight is local: it checks the manifest fingerprint,
+declared policy, version constraints, and locked binary metadata without
+contacting PyPI, npm, GitHub, or GitLab. Run `ixt lock write` when you want to
+resolve upstream again and refresh the lock.
 
 ## 🧰 Commands
 
 | Command                                        | Description                                                           |
 | ---------------------------------------------- | --------------------------------------------------------------------- |
-| `ixt tool add <pkg>`                                | Add a tool to ixt.toml without installing                             |
-| `ixt tool install <pkg>`                            | Install a tool in isolation                                           |
-| `ixt tool install <pkg> --bare`                     | Install the env without exposing any binary                           |
-| `ixt tool uninstall <pkg>`                          | Remove a tool                                                         |
-| `ixt tool list`                                     | List installed tools                                                  |
-| `ixt tool info <pkg>`                               | Show tool details                                                     |
-| `ixt tool upgrade <pkg>`                            | Upgrade a tool                                                        |
-| `ixt tool upgrade --all`                            | Upgrade all tools                                                     |
-| `ixt tool apply`                                    | Sync tools from declarative config                                    |
-| `ixt tool apply --locked --strict`                   | Sync using exact versions and assets from ixt.lock                    |
-| `ixt tool export`                             | Export installed tools as ixt.toml (stdout), preserves install intent |
-| `ixt lock write`                              | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                              | Fail if ixt.lock is missing or stale                                  |
-| `ixt lock diff`                               | Show semantic differences between ixt.toml and ixt.lock               |
+| `ixt tool add <pkg>`                           | Add a tool to ixt.toml without installing                             |
+| `ixt tool install <pkg>`                       | Install a tool in isolation                                           |
+| `ixt tool install <pkg> --bare`                | Install the env without exposing any binary                           |
+| `ixt tool uninstall <pkg>`                     | Remove a tool                                                         |
+| `ixt tool list`                                | List installed tools                                                  |
+| `ixt tool info <pkg>`                          | Show tool details                                                     |
+| `ixt tool upgrade <pkg>`                       | Upgrade a tool                                                        |
+| `ixt tool upgrade --all`                       | Upgrade all tools                                                     |
+| `ixt tool apply`                               | Sync tools from declarative config                                    |
+| `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
+| `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
+| `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
+| `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
-| `ixt tool config <pkg> expose <rules...>`           | Change exposed binaries                                               |
-| `ixt tool config <pkg> inject <dep>`                | Inject a package into the tool's env                                  |
-| `ixt tool config <pkg> uninject <dep>`              | Remove an injected package                                            |
-| `ixt tool config __all__ expose <rules...>`         | Re-expose every installed tool                                        |
-| `ixt tool shell <pkg>`                              | Open a subshell in tool's env                                         |
-| `ixt tool where <pkg>`                              | Print the tool env path                                               |
+| `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
+| `ixt tool config <pkg> inject <dep>`           | Inject a package into the tool's env                                  |
+| `ixt tool config <pkg> uninject <dep>`         | Remove an injected package                                            |
+| `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
+| `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
+| `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |
 | `ixt cache prune`                              | Keep current + previous indexed download artifacts per repository     |
 | `ixt cache clear {downloads,metadata,tmp,all}` | Wipe cache(s); never touches installed tools                          |
-| `ixt runtime info`                            | Show ixt-managed runtime state                                        |
-| `ixt runtime prune [--all]`                   | Remove unused or all ixt-managed runtimes                             |
+| `ixt runtime info`                             | Show ixt-managed runtime state                                        |
+| `ixt runtime prune [--all]`                    | Remove unused or all ixt-managed runtimes                             |
 | `ixt setup path`                               | Add `$IXT_HOME/installed/bin` to PATH                                 |
 | `ixt setup completions --shell zsh`            | Print shell completion code for ixt                                   |
 
@@ -256,7 +260,7 @@ ixt is **not** a runtime version manager (mise, proto, asdf cover that). It mana
 git clone https://gitlab.com/pytgaen-group/ixt.git && cd ixt
 uv sync --group dev
 
-uv run pytest                 # test suite
+uv run pytest                 # hermetic unit suite
 uv run ruff check src/ tests/ # lint
 uv run ruff format src/ tests/ # format
 ```

{ixt_cli-0.9.0 → ixt_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ixt-cli"
-version = "0.9.0" # to bump
+version = "0.10.0" # to bump
 description = "Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -61,14 +61,15 @@ include = [
 # Testing
 [tool.pytest.ini_options]
 minversion = "7.0"
-testpaths = ["tests"]
+testpaths = ["tests/unit"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-addopts = "-ra --strict-markers"
+addopts = '-ra --strict-markers -m "not slow and not network"'
 markers = [
     "unit: unit tests",
     "integration: integration tests",
+    "e2e: end-to-end tests against an installed ixt CLI",
     "platform: platform-specific tests (linux, macos, windows)",
     "slow: tests that bootstrap external runtimes (uv, bun) — skip by default with -m 'not slow'",
     "network: tests that hit the public internet (e.g. real GitHub releases) — opt in with -m 'network'",

{ixt_cli-0.9.0 → ixt_cli-0.10.0}/src/ixt/backends/binary.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
+import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -18,6 +20,7 @@ from ixt.config.flags import is_setup_toml_enabled
 from ixt.config.heuristics import (
     get_name_suffix_tokens,
     get_platform_aliases,
+    is_asset_arch_compatible,
     load_heuristics,
     select_asset,
 )
@@ -29,7 +32,10 @@ from ixt.config.settings import Settings, get_settings
 from ixt.core.backend import BackendType
 from ixt.core.discover import find_executables
 from ixt.core.extract import extract, is_archive
+from ixt.libs.elf import PREFIX_SIZE as ELF_PREFIX_SIZE
+from ixt.libs.elf import parse_elf, read_elf
 from ixt.libs.logger import get_logger, get_verbosity
+from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError, get_range
 from ixt.net.source import Asset, Release, ReleaseSource, RepoSpec, parse_spec
 from ixt.platform import get_arch, get_os
 
@@ -45,6 +51,9 @@ __all__ = [
     "make_source",
 ]
 
+BINARY_ASSET_CACHE_SCHEMA = 2
+_CACHE_ARCHIVE_SUFFIXES = (".tar.bz2", ".tar.gz", ".tar.xz", ".tgz", ".txz", ".zip")
+
 
 # 3.10 lacks typing.NotRequired (added in 3.11) and the project bans
 # third-party deps (typing_extensions). The required-base + total=False
@@ -82,14 +91,27 @@ class SetupMetadata(_SetupMetadataRequired, total=False):
 class AssetSelectionError(RuntimeError):
     """Raised when no suitable asset could be selected for the current platform."""
 
-    def __init__(self, spec: str, release_tag: str, asset_names: list[str]):
+    def __init__(
+        self,
+        spec: str,
+        release_tag: str,
+        asset_names: list[str],
+        unusable: list[tuple[str, str]] | None = None,
+    ):
         self.spec = spec
         self.release_tag = release_tag
         self.asset_names = asset_names
+        self.unusable = unusable or []
         names = ", ".join(asset_names[:10]) or "<none>"
-        super().__init__(
+        message = (
             f"No suitable asset found for '{spec}' (release {release_tag}). Available: {names}"
         )
+        if self.unusable:
+            skipped = ", ".join(
+                f"{name} (needs missing loader {loader})" for name, loader in self.unusable
+            )
+            message += f". Skipped as unrunnable here: {skipped}"
+        super().__init__(message)
 
 
 class BinaryPlatformError(RuntimeError):
@@ -267,10 +289,51 @@ def _cache_dir_for(settings: Settings, repo_spec: RepoSpec) -> Path:
     return settings.cache_dir / host / f"{repo_spec.owner}-{repo_spec.repo}"
 
 
-def _cached_asset(cache_dir: Path, asset_name: str) -> Path | None:
-    """Return the cached asset path if it exists."""
-    path = cache_dir / asset_name
-    if path.exists() and path.stat().st_size > 0:
+def _asset_cache_key(repo_spec: RepoSpec, asset: Asset, *, tag: str) -> str:
+    """Return the stable cache identity for one exact release asset."""
+    identity = json.dumps(
+        {
+            "schema": BINARY_ASSET_CACHE_SCHEMA,
+            "platform": repo_spec.platform,
+            "host": repo_spec.host,
+            "owner": repo_spec.owner,
+            "repo": repo_spec.repo,
+            "tag": tag,
+            "asset": asset.name,
+            "url": asset.url,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(identity.encode()).hexdigest()
+
+
+def _asset_cache_path(
+    downloads_dir: Path,
+    repo_spec: RepoSpec,
+    asset: Asset,
+    *,
+    tag: str,
+) -> Path:
+    """Return a portable path for one exact release asset."""
+    lower_name = asset.name.lower()
+    suffix = next((item for item in _CACHE_ARCHIVE_SUFFIXES if lower_name.endswith(item)), "")
+    if not suffix:
+        match = re.search(r"\.[A-Za-z0-9]{1,10}$", asset.name)
+        suffix = match.group(0) if match is not None else ""
+    key = _asset_cache_key(repo_spec, asset, tag=tag)
+    return downloads_dir / f"assets-v{BINARY_ASSET_CACHE_SCHEMA}" / key / f"asset{suffix}"
+
+
+def _cached_asset(path: Path, expected_size: int = 0) -> Path | None:
+    """Return *path* when it is a non-empty cache entry of the expected size."""
+    try:
+        if not path.is_file():
+            return None
+        size = path.stat().st_size
+    except OSError:
+        return None
+    if 0 < size <= MAX_DOWNLOAD_SIZE and (expected_size <= 0 or size == expected_size):
         return path
     return None
 
@@ -533,9 +596,30 @@ class BinaryBackend:
             log.debug(f"user-forced asset_pattern: {asset_pattern!r}")
         selection_pattern = _selection_pattern(effective_pattern, release.tag)
         if locked_binary is None:
-            asset = self._select_asset(release, selection_pattern, tool_name, spec)
+            try:
+                asset = self._select_asset(
+                    release, selection_pattern, tool_name, spec, repo_spec=repo_spec
+                )
+            except AssetSelectionError:
+                # A synthesized release carries only the asset its pattern named.
+                # If that asset cannot run here, the pattern is wrong for this
+                # host, not merely stale — relearn it against the full release.
+                relearned = self._relearn_release(source, repo_spec, release)
+                if relearned is None:
+                    raise
+                release = relearned
+                selection_pattern = _selection_pattern(effective_pattern, release.tag)
+                asset = self._select_asset(
+                    release, selection_pattern, tool_name, spec, repo_spec=repo_spec
+                )
         else:
             asset = release.assets[0]
+            if not is_asset_arch_compatible(
+                asset.name,
+                heuristics=load_heuristics(),
+                declared_platform=locked_binary.platform,
+            ):
+                raise AssetSelectionError(spec, release.tag, [asset.name])
         log.debug(f"selected asset: {asset.name}")
 
         archive_path = self._download_asset(
@@ -680,23 +764,110 @@ class BinaryBackend:
         asset_pattern: str | None,
         tool_name: str,
         main_spec: str,
+        *,
+        repo_spec: RepoSpec | None = None,
     ) -> Asset:
+        log = get_logger("binary")
         heuristics = load_heuristics()
-        asset = select_asset(
-            release.assets,
-            tool_name,
-            _strip_v_prefix(release.tag),
-            heuristics=heuristics,
-            asset_pattern=asset_pattern,
-            verbose=get_verbosity(),
-        )
-        if asset is None:
-            raise AssetSelectionError(
-                main_spec,
-                release.tag,
-                [a.name for a in release.assets],
+        candidates = list(release.assets)
+        unusable: list[tuple[str, str]] = []
+
+        while candidates:
+            asset = select_asset(
+                candidates,
+                tool_name,
+                _strip_v_prefix(release.tag),
+                heuristics=heuristics,
+                asset_pattern=asset_pattern,
+                verbose=get_verbosity(),
             )
-        return asset
+            if asset is None:
+                break
+
+            loader = self._unrunnable_loader(asset, repo_spec=repo_spec, tag=release.tag)
+            if loader is None:
+                return asset
+
+            log.debug(f"asset skip: {asset.name} needs missing loader {loader}")
+            unusable.append((asset.name, loader))
+            candidates = [a for a in candidates if a.name != asset.name]
+
+        raise AssetSelectionError(
+            main_spec,
+            release.tag,
+            [a.name for a in release.assets],
+            unusable,
+        )
+
+    def _relearn_release(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+    ) -> Release | None:
+        """Re-fetch *release* from the API after its learned pattern proved wrong.
+
+        The fast path synthesizes a release holding only the asset its pattern
+        names, so a pattern pointing at an unrunnable build leaves selection
+        with nothing to fall back on. The pattern is dropped and the real asset
+        list fetched, which lets scoring reach the runnable siblings.
+
+        Returns None when the release already came from the API: there is then
+        no wider list to fall back to, and the caller should surface the
+        original selection error instead.
+        """
+        if (release.resolution_source or "").endswith("-api"):
+            return None
+
+        log = get_logger("binary")
+        log.debug(
+            f"asset pattern for {repo_spec.owner}/{repo_spec.repo} names an unrunnable "
+            "asset — invalidating and refetching from the release API"
+        )
+        from ixt.config import asset_pattern_cache
+
+        asset_pattern_cache.invalidate(repo_spec.owner, repo_spec.repo)
+        self._require_github_api(repo_spec)
+        refetched = source.get_release_by_tag(repo_spec.owner, repo_spec.repo, release.tag)
+        refetched.resolution_source = f"{repo_spec.platform}-api"
+        log.debug(f"release (relearn): {refetched.tag} ({len(refetched.assets)} assets)")
+        return refetched
+
+    def _unrunnable_loader(
+        self,
+        asset: Asset,
+        *,
+        repo_spec: RepoSpec | None,
+        tag: str,
+    ) -> str | None:
+        """Return the loader *asset* needs but this host lacks, else None.
+
+        A cached asset is read from disk; otherwise only the head of the asset
+        is fetched over HTTP Range, which keeps a doomed candidate from costing
+        a full download. Only bare binaries can be checked this way — an
+        archive reveals nothing at offset zero, so those are validated after
+        extraction by ``find_executables`` instead.
+
+        Any doubt resolves to None: a server without Range support, a network
+        hiccup, or a truncated prefix all fall through to the normal path.
+        """
+        if os.name == "nt" or is_archive(asset.name):
+            return None
+        if repo_spec is not None:
+            cache_path = _asset_cache_path(self.settings.downloads_dir, repo_spec, asset, tag=tag)
+            cached = _cached_asset(cache_path, asset.size)
+            if cached is not None:
+                # Already on disk: judge the real file, no request needed.
+                info = read_elf(cached)
+                return info.interpreter if info is not None and info.loader_missing() else None
+
+        head = get_range(asset.url, ELF_PREFIX_SIZE)
+        if head is None:
+            return None
+        info = parse_elf(head)
+        if info is None or not info.loader_missing():
+            return None
+        return info.interpreter
 
     def uninstall_package(self, env_dir: Path, package: str) -> None:
         """No-op — binary tools are atomic (uninstall removes the whole env)."""
@@ -950,15 +1121,28 @@ class BinaryBackend:
         upgrade: bool = False,
     ) -> Path:
         """Download an asset, using cache when available."""
-        cached = _cached_asset(cache_dir, asset.name)
+        if asset.size > MAX_DOWNLOAD_SIZE:
+            raise DownloadTooLargeError(asset.url, MAX_DOWNLOAD_SIZE, asset.size)
+
+        cache_key = _asset_cache_key(repo_spec, asset, tag=tag)
+        dest = _asset_cache_path(self.settings.downloads_dir, repo_spec, asset, tag=tag)
+        cached = _cached_asset(dest, asset.size)
         if cached is not None and not upgrade:
-            self._record_download(repo_spec, asset, cached, tag=tag)
+            self._record_download(repo_spec, asset, cached, tag=tag, cache_key=cache_key)
             return cached
 
-        cache_dir.mkdir(parents=True, exist_ok=True)
-        dest = cache_dir / asset.name
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.unlink(missing_ok=True)
         source.download_asset(asset.url, dest)
-        self._record_download(repo_spec, asset, dest, tag=tag)
+        if dest.is_file() and dest.stat().st_size > MAX_DOWNLOAD_SIZE:
+            actual_size = dest.stat().st_size
+            dest.unlink(missing_ok=True)
+            raise DownloadTooLargeError(asset.url, MAX_DOWNLOAD_SIZE, actual_size)
+        if _cached_asset(dest, asset.size) is None:
+            dest.unlink(missing_ok=True)
+            expected = f"{asset.size} bytes" if asset.size > 0 else "a non-empty file"
+            raise RuntimeError(f"Downloaded asset {asset.name!r} does not match {expected}")
+        self._record_download(repo_spec, asset, dest, tag=tag, cache_key=cache_key)
         return dest
 
     def _record_download(
@@ -968,6 +1152,7 @@ class BinaryBackend:
         path: Path,
         *,
         tag: str,
+        cache_key: str,
     ) -> None:
         """Index the downloaded binary asset for later cache pruning."""
         from ixt.core.cache import record_download
@@ -984,4 +1169,5 @@ class BinaryBackend:
             asset_url=asset.url,
             asset_size=asset.size,
             path=path,
+            cache_key=cache_key,
         )