ixt-cli 0.8.1__tar.gz → 0.9.1__tar.gz

{ixt_cli-0.8.1 → ixt_cli-0.9.1}/.gitignore

@@ -150,3 +150,4 @@ ixt.egg-info
 
 .memsearch/
 .pyscn/
+.pi/

ixt_cli-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaëtan Montury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{ixt_cli-0.8.1 → ixt_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ixt-cli
-Version: 0.8.1
+Version: 0.9.1
 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
@@ -8,6 +8,7 @@ Project-URL: Issues, https://gitlab.com/pytgaen-group/ixt/-/issues
 Project-URL: Documentation, https://ixt-39f604.gitlab.io
 Author-email: Gaëtan Montury <10528250-pytgaen@users.noreply.gitlab.com>
 License: MIT
+License-File: LICENSE
 Keywords: cli,github,isolation,npm,package-manager,pypi,tool
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -33,8 +34,10 @@ Description-Content-Type: text/markdown
 <h1 align="center">ixt — Universal CLI Tool Isolator</h1>
 
 <p align="center">
-  <a href="https://gitlab.com/pytgaen-group/ixt/-/releases"><img src="https://img.shields.io/gitlab/v/release/pytgaen-group/ixt?label=release" alt="Release"></a>
-  <a href="https://gitlab.com/pytgaen-group/ixt/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline-status/pytgaen-group/ixt?branch=main" alt="Pipeline"></a>
+  <a href="https://gitlab.com/pytgaen-group/ixt/-/tags"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F81169049%2Frepository%2Ftags%3Fper_page%3D1&amp;query=%24%5B0%5D.name&amp;label=release" alt="Release"></a>
+  <a href="https://gitlab.com/pytgaen-group/ixt/-/blob/main/.gitlab-ci.yml"><img src="https://img.shields.io/badge/build-GitLab%20CI-blue?logo=gitlab" alt="Build: GitLab CI"></a>
+  <a href="https://pypi.org/project/ixt-cli/"><img src="https://img.shields.io/pypi/v/ixt-cli?label=pypi" alt="PyPI"></a>
+  <a href="https://pepy.tech/projects/ixt-cli"><img src="https://static.pepy.tech/badge/ixt-cli/month" alt="PyPI Downloads"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
 </p>
@@ -48,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)
@@ -183,34 +186,59 @@ ixt tool install sharkdp/fd@10              # latest 10.x.x
 ixt tool install ruff>=0.5.0                # PEP 508 (Python)
 ```
 
+## 🔒 Declarative locks
+
+`ixt.toml` is the human-edited intent: which tools you want, with optional
+version bounds, exposure rules, and injections. `ixt.lock` is generated from
+that intent and records the exact resolved versions and binary release assets.
+
+For teams and CI, commit both files:
+
+```bash
+ixt lock write
+ixt lock check
+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. 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 export`                             | Export installed tools as ixt.toml (stdout), preserves install intent |
+| `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 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                                   |
 
@@ -219,7 +247,8 @@ ixt tool install ruff>=0.5.0                # PEP 508 (Python)
 ```
 $IXT_HOME/                # default ~/.local/share/ixt (respects $XDG_DATA_HOME)
 ├── config/
-│   ├── ixt.toml
+│   ├── ixt.toml          # global declarative manifest fallback
+│   ├── ixt.lock          # global lock when using the global ixt.toml
 │   ├── registry.toml
 │   └── heuristics.toml
 └── installed/
@@ -259,17 +288,17 @@ 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
 ```
 
 ## 🤝 Contributing
 
-Development happens on **GitLab**: <https://gitlab.com/pytgaen-group/ixt>. The GitHub repository (if present) is a **read-only mirror** — please open issues and merge requests on GitLab.
+Development happens on **GitLab**: <https://gitlab.com/pytgaen-group/ixt>. Any GitHub repository for this project is a **read-only mirror** of GitLab; it is not the review or issue tracker. Please open issues and merge requests on GitLab.
 
 Bug reports and reproduction recipes are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details, or open an issue to start a discussion.
 
 ## 📄 License
 
-MIT
+MIT. See [`LICENSE`](LICENSE).

{ixt_cli-0.8.1 → ixt_cli-0.9.1}/README.md

@@ -5,8 +5,10 @@
 <h1 align="center">ixt — Universal CLI Tool Isolator</h1>
 
 <p align="center">
-  <a href="https://gitlab.com/pytgaen-group/ixt/-/releases"><img src="https://img.shields.io/gitlab/v/release/pytgaen-group/ixt?label=release" alt="Release"></a>
-  <a href="https://gitlab.com/pytgaen-group/ixt/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline-status/pytgaen-group/ixt?branch=main" alt="Pipeline"></a>
+  <a href="https://gitlab.com/pytgaen-group/ixt/-/tags"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F81169049%2Frepository%2Ftags%3Fper_page%3D1&amp;query=%24%5B0%5D.name&amp;label=release" alt="Release"></a>
+  <a href="https://gitlab.com/pytgaen-group/ixt/-/blob/main/.gitlab-ci.yml"><img src="https://img.shields.io/badge/build-GitLab%20CI-blue?logo=gitlab" alt="Build: GitLab CI"></a>
+  <a href="https://pypi.org/project/ixt-cli/"><img src="https://img.shields.io/pypi/v/ixt-cli?label=pypi" alt="PyPI"></a>
+  <a href="https://pepy.tech/projects/ixt-cli"><img src="https://static.pepy.tech/badge/ixt-cli/month" alt="PyPI Downloads"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
 </p>
@@ -20,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)
@@ -155,34 +157,59 @@ ixt tool install sharkdp/fd@10              # latest 10.x.x
 ixt tool install ruff>=0.5.0                # PEP 508 (Python)
 ```
 
+## 🔒 Declarative locks
+
+`ixt.toml` is the human-edited intent: which tools you want, with optional
+version bounds, exposure rules, and injections. `ixt.lock` is generated from
+that intent and records the exact resolved versions and binary release assets.
+
+For teams and CI, commit both files:
+
+```bash
+ixt lock write
+ixt lock check
+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. 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 export`                             | Export installed tools as ixt.toml (stdout), preserves install intent |
+| `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 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                                   |
 
@@ -191,7 +218,8 @@ ixt tool install ruff>=0.5.0                # PEP 508 (Python)
 ```
 $IXT_HOME/                # default ~/.local/share/ixt (respects $XDG_DATA_HOME)
 ├── config/
-│   ├── ixt.toml
+│   ├── ixt.toml          # global declarative manifest fallback
+│   ├── ixt.lock          # global lock when using the global ixt.toml
 │   ├── registry.toml
 │   └── heuristics.toml
 └── installed/
@@ -231,17 +259,17 @@ 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
 ```
 
 ## 🤝 Contributing
 
-Development happens on **GitLab**: <https://gitlab.com/pytgaen-group/ixt>. The GitHub repository (if present) is a **read-only mirror** — please open issues and merge requests on GitLab.
+Development happens on **GitLab**: <https://gitlab.com/pytgaen-group/ixt>. Any GitHub repository for this project is a **read-only mirror** of GitLab; it is not the review or issue tracker. Please open issues and merge requests on GitLab.
 
 Bug reports and reproduction recipes are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details, or open an issue to start a discussion.
 
 ## 📄 License
 
-MIT
+MIT. See [`LICENSE`](LICENSE).

{ixt_cli-0.8.1 → ixt_cli-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ixt-cli"
-version = "0.8.1" # to bump
+version = "0.9.1" # to bump
 description = "Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,10 +37,6 @@ dev = [
     "pytest-cov>=4.1",
     "pyright>=1.1",
 ]
-# Standalone binary build (Nuitka). Not a runtime dependency — install with
-# `uv sync --group build`. [onefile] pulls zstandard for payload compression.
-# See notes/standalone-build.md.
-build = ["nuitka[onefile]>=2.5"]
 
 [project.scripts]
 ixt = "ixt.cli:main"
@@ -65,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.8.1 → ixt_cli-0.9.1}/src/ixt/backends/binary.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 from dataclasses import dataclass, field
@@ -18,22 +19,27 @@ 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,
 )
 
 if TYPE_CHECKING:
+    from ixt.config.lockfile import BinaryLockMetadata
     from ixt.config.setup_toml import SetupConfig
 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.logger import get_logger, get_verbosity
+from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError
 from ixt.net.source import Asset, Release, ReleaseSource, RepoSpec, parse_spec
+from ixt.platform import get_arch, get_os
 
 __all__ = [
     "AssetSelectionError",
     "BinaryBackend",
+    "BinaryPlatformError",
     "BinarySpecError",
     "HookEntry",
     "SetupMetadata",
@@ -42,6 +48,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
@@ -89,6 +98,31 @@ class AssetSelectionError(RuntimeError):
         )
 
 
+class BinaryPlatformError(RuntimeError):
+    """Raised when extracted executables are incompatible with the current platform."""
+
+    def __init__(
+        self,
+        spec: str,
+        release_tag: str,
+        asset_name: str,
+        rejected: list[tuple[Path, str]],
+    ):
+        self.spec = spec
+        self.release_tag = release_tag
+        self.asset_name = asset_name
+        self.rejected = rejected
+        platform = f"{get_os().value}/{get_arch().value}"
+        details = ", ".join(
+            f"{path.name} ({format_label})"
+            for path, format_label in sorted(rejected, key=lambda item: str(item[0]))
+        )
+        super().__init__(
+            f"No executable compatible with {platform} found for '{spec}' "
+            f"(release {release_tag}, asset {asset_name}). Rejected: {details}"
+        )
+
+
 class BinarySpecError(ValueError):
     """Raised when a spec cannot be parsed as a binary backend spec."""
 
@@ -239,10 +273,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
 
@@ -396,6 +471,7 @@ class BinaryBackend:
         setup_path: Path | None = None,
         asset_pattern: str | None = None,
         known_tag: str | None = None,
+        locked_binary: BinaryLockMetadata | None = None,
         use_cache: bool = True,
     ) -> dict | None:
         """Compatibility adapter for the shared backend protocol."""
@@ -410,6 +486,7 @@ class BinaryBackend:
             setup_path=setup_path,
             asset_pattern=asset_pattern,
             known_tag=known_tag,
+            locked_binary=locked_binary,
             use_cache=use_cache,
         )
 
@@ -422,6 +499,7 @@ class BinaryBackend:
         setup_path: Path | None = None,
         asset_pattern: str | None = None,
         known_tag: str | None = None,
+        locked_binary: BinaryLockMetadata | None = None,
         use_cache: bool = True,
     ) -> dict | None:
         """Resolve, download, extract, and discover one atomic binary tool.
@@ -460,24 +538,34 @@ class BinaryBackend:
         )
         release_pattern_name = setup.name if setup and setup.name else None
 
-        # Reuse the release already fetched during version resolution (e.g. an
-        # upgrade or a dry-run within the TTL window). This skips a second API
-        # call — the only option for GitLab, whose asset URLs can't be rebuilt
-        # from a pattern like GitHub's.
-        release = self._cached_release(spec) if use_cache and not repo_spec.version else None
-        if release is not None:
-            log.debug(f"release (resolve cache): {release.tag} ({len(release.assets)} assets)")
-        else:
-            release = self._fetch_release(
-                source,
-                repo_spec,
-                env_dir=env_dir,
-                upgrade=upgrade,
-                known_tag=known_tag,
-                asset_pattern=release_pattern,
-                pattern_name=release_pattern_name,
+        if locked_binary is not None:
+            if not repo_spec.version:
+                raise BinarySpecError("locked binary install requires a pinned release tag")
+            release = Release(
+                tag=repo_spec.version,
+                assets=[Asset(name=locked_binary.asset, url=locked_binary.url)],
+                resolution_source="lockfile",
             )
-            log.debug(f"release: {release.tag} ({len(release.assets)} assets)")
+            log.debug(f"release (lockfile): {release.tag} ({locked_binary.asset})")
+        else:
+            # Reuse the release already fetched during version resolution (e.g. an
+            # upgrade or a dry-run within the TTL window). This skips a second API
+            # call — the only option for GitLab, whose asset URLs can't be rebuilt
+            # from a pattern like GitHub's.
+            release = self._cached_release(spec) if use_cache and not repo_spec.version else None
+            if release is not None:
+                log.debug(f"release (resolve cache): {release.tag} ({len(release.assets)} assets)")
+            else:
+                release = self._fetch_release(
+                    source,
+                    repo_spec,
+                    env_dir=env_dir,
+                    upgrade=upgrade,
+                    known_tag=known_tag,
+                    asset_pattern=release_pattern,
+                    pattern_name=release_pattern_name,
+                )
+                log.debug(f"release: {release.tag} ({len(release.assets)} assets)")
 
         if setup is None and not setup_resolved:
             setup = self._resolve_setup(
@@ -491,7 +579,16 @@ class BinaryBackend:
         if asset_pattern:
             log.debug(f"user-forced asset_pattern: {asset_pattern!r}")
         selection_pattern = _selection_pattern(effective_pattern, release.tag)
-        asset = self._select_asset(release, selection_pattern, tool_name, spec)
+        if locked_binary is None:
+            asset = self._select_asset(release, selection_pattern, tool_name, 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(
@@ -512,8 +609,16 @@ class BinaryBackend:
         log.debug(f"extracted to: {result.root}")
 
         heuristics = load_heuristics()
-        executables = find_executables(result.root, expose=heuristics.expose, log=log)
+        rejected_executables: list[tuple[Path, str]] = []
+        executables = find_executables(
+            result.root,
+            expose=heuristics.expose,
+            log=log,
+            rejected=rejected_executables,
+        )
         log.debug(f"executables: {[e.name for e in executables]}")
+        if not executables and rejected_executables:
+            raise BinaryPlatformError(spec, release.tag, asset.name, rejected_executables)
 
         binaries = {exe.name: str(exe) for exe in executables}
 
@@ -898,15 +1003,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(
@@ -916,6 +1034,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
@@ -932,4 +1051,5 @@ class BinaryBackend:
             asset_url=asset.url,
             asset_size=asset.size,
             path=path,
+            cache_key=cache_key,
         )