seampact-ir 1.0.0__tar.gz

seampact_ir-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/

seampact_ir-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Metral
+
+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.

seampact_ir-1.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: seampact-ir
+Version: 1.0.0
+Summary: The seampact IR model, naming and reader for Python generators.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jsonschema==4.26.0
+Requires-Dist: ruamel-yaml==0.19.1
+Provides-Extra: compiler
+Requires-Dist: seampact-compiler==1.0.0; extra == 'compiler'
+Description-Content-Type: text/markdown
+
+The seampact IR model generated from the IR JSON Schema, the native naming, the IR reader, the bundle verifier and the compiler binary runner, for Python generators.

seampact_ir-1.0.0/README.md

@@ -0,0 +1 @@
+The seampact IR model generated from the IR JSON Schema, the native naming, the IR reader, the bundle verifier and the compiler binary runner, for Python generators.

seampact_ir-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-ir"
+version = "1.0.0"
+description = "The seampact IR model, naming and reader for Python generators."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["jsonschema==4.26.0", "ruamel.yaml==0.19.1"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# The compiler binary of this platform, for a `path` source or the OpenAPI documents of an app config; a bundle-only
+# app with `openapi: none` never needs it.
+compiler = ["seampact-compiler==1.0.0"]
+
+# PEP 420: `seampact` is a namespace shared by every seampact distribution, so it has no `__init__.py`.
+[project.scripts]
+seampact = "seampact.ir.run.command:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seampact"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/seampact", "LICENSE"]
+
+[tool.uv.sources]
+seampact-compiler = { workspace = true }

seampact_ir-1.0.0/src/seampact/ir/__init__.py

@@ -0,0 +1 @@
+"""The seampact IR for Python generators (ADR 0010): the generated model, the native naming and the reader."""

seampact_ir-1.0.0/src/seampact/ir/binary/__init__.py

@@ -0,0 +1,23 @@
+"""The compiler binary of a Python build (ADR 0010): wheel lookup, pin, platform, private cache and runner."""
+
+from seampact.ir.binary.compiler_binary import install_compiler_binary
+from seampact.ir.binary.documents_command import DocumentsCommand
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+from seampact.ir.binary.host_libc import HostLibc
+from seampact.ir.binary.host_platform import HostPlatform
+from seampact.ir.binary.installed_binary import InstalledBinary
+from seampact.ir.binary.runner import CompileOutput, DocumentsOutput, compile_with_binary, documents_with_binary
+
+__all__ = [
+    "BinaryFailureCode",
+    "BinaryRefusedError",
+    "CompileOutput",
+    "DocumentsCommand",
+    "DocumentsOutput",
+    "HostLibc",
+    "HostPlatform",
+    "InstalledBinary",
+    "compile_with_binary",
+    "documents_with_binary",
+    "install_compiler_binary",
+]

seampact_ir-1.0.0/src/seampact/ir/binary/absolute_path.py

@@ -0,0 +1,43 @@
+"""Absolute paths for the binary channel: a path is made absolute once, before any check, and then used as is, so the
+file checked and the file started are one file whatever directory the child starts in."""
+
+import os
+import re
+import sys
+from typing import Final
+
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+
+_WINDOWS_DRIVE_PATH: Final = re.compile(r"[A-Za-z]:[\\/]")
+
+
+def is_absolute(path: str) -> bool:
+    """Whether `path` is absolute on this host: `is_absolute_on_windows` on Windows, else `is_absolute_on_posix`."""
+    return is_absolute_on_windows(path) if sys.platform == "win32" else is_absolute_on_posix(path)
+
+
+def is_absolute_on_posix(path: str) -> bool:
+    """A path from the filesystem root; `\\x` and `C:/x` are relative names on POSIX."""
+    return path.startswith("/")
+
+
+def is_absolute_on_windows(path: str) -> bool:
+    """A drive path, a UNC path or a path from the root of the current drive."""
+    return path.startswith(("/", "\\")) or _WINDOWS_DRIVE_PATH.match(path) is not None
+
+
+def resolved(path: str) -> str:
+    """`path` itself when absolute, else `path` below the working directory of this process."""
+    if is_absolute(path):
+        return path
+
+    try:
+        working_directory = os.getcwd()
+    except OSError as error:
+        raise BinaryRefusedError(
+            BinaryFailureCode.COMPILE_FAILED,
+            f"The relative path '{path}' cannot be made absolute: the working directory cannot be read ({error}).",
+            "Run seampact from a directory your user can read, or pass absolute paths.",
+        ) from error
+
+    return os.path.join(working_directory, path)

seampact_ir-1.0.0/src/seampact/ir/binary/binaries.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0.0",
+  "sha256": {
+    "seampact-linux-x64": "e3a6e749206f27ed2883e4cd8ea0f3c736bb629c91134eaafef64c147ed7ee2f",
+    "seampact-linux-arm64": "19b32653f54578dd8d3c0bc1ef929ea7211b55350308800da38b139712241c6b",
+    "seampact-darwin-x64": "4c6e11153456339667dc35b1b8c3ef7b059151fbade0c78d98e1af07cc2af3c7",
+    "seampact-darwin-arm64": "87e004d1b5e9ee4afe322b87e04bd0982c326adc01c8f206227d4f8215305775",
+    "seampact-win32-x64.exe": "3f56467f4de7b5a2583011b85594592a0c37af88c4ff493482d3cff5d7ad8b09"
+  }
+}

seampact_ir-1.0.0/src/seampact/ir/binary/cache_root.py

@@ -0,0 +1,52 @@
+"""The binary cache root: `$XDG_CACHE_HOME/seampact`, else `$HOME/.cache/seampact`; on Windows
+`%LOCALAPPDATA%\\seampact`, whose ACL is per user. A relative `XDG_CACHE_HOME` is ignored, as the XDG specification
+says; any other relative variable is refused by name, so the cache never depends on the directory a command
+starts in."""
+
+from collections.abc import Mapping
+from typing import Final
+
+from seampact.ir.binary.absolute_path import is_absolute_on_posix, is_absolute_on_windows
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+
+_DIRECTORY: Final = "seampact"
+# A relative value of this variable is ignored (XDG Base Directory specification); others are refused.
+_IGNORED_WHEN_RELATIVE: Final = "XDG_CACHE_HOME"
+
+
+def locate_cache_root(environment: Mapping[str, str], *, windows: bool) -> str:
+    """An absolute path. Raises `binary.cache-unavailable` when none of the variables is set or the one read is
+    relative."""
+    candidates = [("LOCALAPPDATA", "")] if windows else [(_IGNORED_WHEN_RELATIVE, ""), ("HOME", "/.cache")]
+    separator = "\\" if windows else "/"
+
+    for variable, below in candidates:
+        base = environment.get(variable, "")
+        is_absolute = is_absolute_on_windows(base) if windows else is_absolute_on_posix(base)
+
+        if base == "" or (not is_absolute and variable == _IGNORED_WHEN_RELATIVE):
+            continue
+
+        if not is_absolute:
+            raise _relative(variable, base)
+
+        return f"{base.rstrip('/\\')}{below}{separator}{_DIRECTORY}"
+
+    names = ", ".join(variable for variable, _ in candidates)
+
+    raise BinaryRefusedError(
+        BinaryFailureCode.CACHE_UNAVAILABLE,
+        f"No cache directory for the compiler binary: none of {names} is set.",
+        "Run seampact as a Windows user with a profile (LOCALAPPDATA set)."
+        if windows
+        else "Set XDG_CACHE_HOME or HOME to a directory private to your user.",
+    )
+
+
+def _relative(variable: str, value: str) -> BinaryRefusedError:
+    return BinaryRefusedError(
+        BinaryFailureCode.CACHE_UNAVAILABLE,
+        f"{variable} is the relative path '{value}', so the binary cache would depend on the directory seampact "
+        "starts in.",
+        f'Set {variable} to an absolute path, such as "$PWD/{value}" in your CI configuration.',
+    )

seampact_ir-1.0.0/src/seampact/ir/binary/cache_safety.py

@@ -0,0 +1,25 @@
+"""The cache checks run on the private copy of the binary before each start (`binary.cache-unsafe`)."""
+
+from typing import Protocol
+
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+
+
+class CacheSafety(Protocol):
+    def create_private_directory(self, directory: str) -> None:
+        """Creates the cache root, each missing directory on its way and `directory` owner-only, whatever the
+        umask."""
+        ...
+
+    def refuse_unsafe(self, copy_path: str, cache_root: str) -> None:
+        """`cache_root` is the real path of the cache root, which `copy_path` is below. Raises `binary.cache-unsafe`,
+        naming the path."""
+        ...
+
+
+def unsafe_cache_path(path: str, problem: str, fix: str) -> BinaryRefusedError:
+    return BinaryRefusedError(
+        BinaryFailureCode.CACHE_UNSAFE,
+        f"The binary cache path '{path}' {problem}; seampact runs only a binary no other user can change.",
+        fix,
+    )

seampact_ir-1.0.0/src/seampact/ir/binary/child_environment.py

@@ -0,0 +1,15 @@
+"""The environment the binary starts with: only the variables of its contract, `TMPDIR`, `TEMP`, `TMP` and, on
+Windows, `SystemRoot`, so no code the environment names (an OpenSSL configuration, a `NODE_OPTIONS` require) runs
+inside the pinned binary. Windows names are case-insensitive."""
+
+from collections.abc import Mapping
+from typing import Final
+
+_CONTRACT_VARIABLES: Final = ("TMPDIR", "TEMP", "TMP")
+_WINDOWS_VARIABLES: Final = ("SYSTEMROOT",)
+
+
+def child_environment(parent: Mapping[str, str], *, windows: bool) -> dict[str, str]:
+    allowed = (*_CONTRACT_VARIABLES, *_WINDOWS_VARIABLES) if windows else _CONTRACT_VARIABLES
+
+    return {name: value for name, value in parent.items() if (name.upper() if windows else name) in allowed}

seampact_ir-1.0.0/src/seampact/ir/binary/compiler_binary.py

@@ -0,0 +1,115 @@
+"""The compiler binary of a Python build: pinned by the root project's `[tool.seampact.binary]` (a dependency's is
+refused) or the pins `seampact-ir` embeds, copied or downloaded into the private content-addressed cache, and run only
+from there. A `path` override is copied; a `version` override downloads the release asset of this host, and a `url`
+override the asset of its mirror. With the embedded pins, the binary is the file of the `seampact-compiler` wheel for
+this host. Each is checked against its pin. A development build embeds no pin: without an override it is refused by
+name (`binary.unpublished`)."""
+
+from collections.abc import Callable, Mapping
+from typing import Final
+
+from seampact.ir.binary.cache_root import locate_cache_root
+from seampact.ir.binary.cache_safety import CacheSafety
+from seampact.ir.binary.dependency_overrides import refuse_dependency_overrides
+from seampact.ir.binary.download import BinaryDownload
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+from seampact.ir.binary.host_platform import HostPlatform
+from seampact.ir.binary.installed_binary import InstalledBinary
+from seampact.ir.binary.installer import install_binary, install_downloaded_binary
+from seampact.ir.binary.override import BinaryOverride, BinaryOverrideSource
+from seampact.ir.binary.pins import embedded_pins
+from seampact.ir.binary.posix_cache_safety import PosixCacheSafety
+from seampact.ir.binary.root_project import RootProject
+from seampact.ir.binary.wheel import COMPILER_DISTRIBUTION, wheel_binary_path
+from seampact.ir.binary.windows_cache_safety import WindowsCacheSafety, locate_user_profile
+
+_FILE_NAME: Final = "seampact"
+_WINDOWS_FILE_NAME: Final = "seampact.exe"
+# Installs the pinned binary into a cache root, under a file name and a cache rule.
+_Install = Callable[[str, str, CacheSafety], InstalledBinary]
+
+_UNPUBLISHED_FIX: Final = (
+    'Set [tool.seampact.binary] in your root pyproject.toml to path = "<your build of the compiler>" and '
+    'sha256 = "<its SHA-256>", or use a bundle source, which needs no binary.'
+)
+
+
+def install_compiler_binary(
+    project_directory: str,
+    host: HostPlatform,
+    environment: Mapping[str, str],
+    safety: CacheSafety | None = None,
+    download: BinaryDownload | None = None,
+) -> InstalledBinary:
+    """`environment` holds the variables of this process. `safety` is the host's cache rule and `download` the
+    GitHub releases unless a test injects its own. Raises `BinaryRefusedError`."""
+    download = download if download is not None else BinaryDownload()
+    root = RootProject.locate(project_directory)
+    refuse_dependency_overrides(root)
+    override = root.binary_override()
+
+    install = _pinned_install(override, host, download)
+    cache_root = locate_cache_root(environment, windows=host.is_windows)
+    cache_safety = safety if safety is not None else _host_cache_safety(host, environment)
+
+    return install(cache_root, _WINDOWS_FILE_NAME if host.is_windows else _FILE_NAME, cache_safety)
+
+
+def _pinned_install(override: BinaryOverride | None, host: HostPlatform, download: BinaryDownload) -> _Install:
+    """How the pinned binary goes into a cache root: copied from the wheel or a `path`, or downloaded. The pins are
+    read before the cache is located."""
+    if override is None:
+        wheel_file, wheel_sha256 = _wheel_source(host)
+
+        return lambda cache_root, file_name, safety: install_binary(
+            wheel_file, wheel_sha256, cache_root, file_name, safety
+        )
+
+    # Only a `path` override carries a single hash.
+    if override.sha256 is not None:
+        path, path_sha256 = override.value, override.sha256
+
+        return lambda cache_root, file_name, safety: install_binary(path, path_sha256, cache_root, file_name, safety)
+
+    asset = host.asset_name()
+    url = (
+        BinaryDownload.mirror_url(override.value, asset)
+        if override.source is BinaryOverrideSource.URL
+        else download.release_url(override.value, asset)
+    )
+    asset_sha256 = override.sha256_by_asset[asset]
+
+    return lambda cache_root, file_name, safety: install_downloaded_binary(
+        url, asset_sha256, cache_root, file_name, safety, download
+    )
+
+
+def _host_cache_safety(host: HostPlatform, environment: Mapping[str, str]) -> CacheSafety:
+    return WindowsCacheSafety(locate_user_profile(environment)) if host.is_windows else PosixCacheSafety()
+
+
+def _wheel_source(host: HostPlatform) -> tuple[str, str]:
+    """The wheel's file for this host and the pinned hash it must have."""
+    pins = embedded_pins()
+
+    if pins is None:
+        raise BinaryRefusedError(
+            BinaryFailureCode.UNPUBLISHED,
+            "This seampact-ir is a development build: it embeds no binary pin, so it has no binary to run.",
+            _UNPUBLISHED_FIX,
+        )
+
+    # With pins, the host decides the asset first, so an unsupported host learns its own fixes.
+    asset = host.asset_name()
+    installed = wheel_binary_path(asset)
+
+    if installed is None:
+        raise BinaryRefusedError(
+            BinaryFailureCode.UNPUBLISHED,
+            f"This seampact-ir pins the compiler {pins.version}, but no installed {COMPILER_DISTRIBUTION} wheel holds "
+            f"'{asset}', the binary of this platform.",
+            f"Install seampact-ir[compiler] ({COMPILER_DISTRIBUTION} {pins.version}), or set [tool.seampact.binary] "
+            'in your root pyproject.toml to url = "<a mirror of the release assets>" with the sha256 of each asset.',
+        )
+
+    return installed, pins.sha256_by_asset[asset]

seampact_ir-1.0.0/src/seampact/ir/binary/dependency_overrides.py

@@ -0,0 +1,92 @@
+"""Refuses a `[tool.seampact.binary]` table set outside the root project (`binary.override-not-root`), so a
+dependency never chooses the binary the build runs. The sources it reads are the pyproject files a Python build can
+reach: the members of the root's uv workspace and the local directories installed distributions record in
+`direct_url.json` (path dependencies, editable installs)."""
+
+import glob
+import json
+import os
+from collections.abc import Iterator
+from importlib import metadata
+from typing import Final
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+from seampact.ir.binary.root_project import PYPROJECT_FILE, RootProject, tool_table
+from seampact.ir.https.untrusted_text import quoted
+
+_FILE_SCHEME: Final = "file"
+_DIRECT_URL_FILE: Final = "direct_url.json"
+
+
+def refuse_dependency_overrides(root: RootProject) -> None:
+    root_file = os.path.realpath(root.pyproject_file)
+
+    for name, pyproject_file in _reachable_pyproject_files(root):
+        if os.path.realpath(pyproject_file) == root_file:
+            continue
+
+        tool = tool_table(pyproject_file)
+        seampact = tool.get("seampact")
+
+        if isinstance(seampact, dict) and "binary" in seampact:
+            raise BinaryRefusedError(
+                BinaryFailureCode.OVERRIDE_NOT_ROOT,
+                f"'{pyproject_file}' of {name} sets `tool.seampact.binary`; only the root project's "
+                f"'{root.pyproject_file}' chooses the compiler binary.",
+                f"Remove the table from '{pyproject_file}', or set the override in your own {PYPROJECT_FILE}.",
+            )
+
+
+def _reachable_pyproject_files(root: RootProject) -> Iterator[tuple[str, str]]:
+    yield from _workspace_members(root)
+    yield from _local_installs()
+
+
+def _workspace_members(root: RootProject) -> Iterator[tuple[str, str]]:
+    if not os.path.isfile(root.pyproject_file):
+        return
+
+    workspace = _table(_table(tool_table(root.pyproject_file).get("uv")).get("workspace"))
+    members = workspace.get("members", [])
+
+    for pattern in members if isinstance(members, list) else []:
+        for directory in sorted(glob.glob(os.path.join(root.directory, str(pattern)))):
+            pyproject_file = os.path.join(directory, PYPROJECT_FILE)
+
+            if os.path.isfile(pyproject_file):
+                yield f"the workspace member {quoted(os.path.basename(directory))}", pyproject_file
+
+
+def _local_installs() -> Iterator[tuple[str, str]]:
+    for distribution in metadata.distributions():
+        recorded = distribution.read_text(_DIRECT_URL_FILE)
+        url = _local_directory_url(recorded)
+
+        if url is None:
+            continue
+
+        pyproject_file = os.path.join(url2pathname(unquote(urlparse(url).path)), PYPROJECT_FILE)
+
+        if os.path.isfile(pyproject_file):
+            yield f"the installed package {quoted(distribution.metadata['Name'])}", pyproject_file
+
+
+def _local_directory_url(recorded: str | None) -> str | None:
+    if recorded is None:
+        return None
+
+    try:
+        direct_url = json.loads(recorded)
+    except ValueError:
+        # A malformed record belongs to the installer that wrote it; it names no local directory.
+        return None
+
+    url = direct_url.get("url") if isinstance(direct_url, dict) else None
+
+    return url if isinstance(url, str) and url.startswith(f"{_FILE_SCHEME}:") and "dir_info" in direct_url else None
+
+
+def _table(value: object) -> dict[str, object]:
+    return value if isinstance(value, dict) else {}

seampact_ir-1.0.0/src/seampact/ir/binary/documents_command.py

@@ -0,0 +1,14 @@
+"""The binary's commands on an app config's OpenAPI documents (ADR 0010): `generate`, `generate --force`, which
+overwrites a document edited by hand, and `check`."""
+
+from enum import Enum
+
+
+class DocumentsCommand(Enum):
+    GENERATE = ("generate",)
+    GENERATE_OVERWRITING_HAND_EDITS = ("generate", "--force")
+    CHECK = ("check",)
+
+    @property
+    def arguments(self) -> list[str]:
+        return list(self.value)

seampact_ir-1.0.0/src/seampact/ir/binary/download.py

@@ -0,0 +1,73 @@
+"""Where the compiler binary is downloaded from, and how (ADR 0010, "Fetch"): a release asset of the seampact GitHub
+releases, or a mirror base URL to which `/<asset>` is appended, so a base with a query or a fragment is refused. The
+download is `HttpsDownload`'s, with the system's certificate authorities and no proxy, as the bundle channel's, a
+deadline sized for a binary of about 100 MB on a slow link, and a cap well above any release asset."""
+
+from collections.abc import Callable
+from typing import Final
+from urllib.parse import quote
+
+from seampact.ir.binary.failure import BinaryFailureCode, BinaryRefusedError
+from seampact.ir.https import HttpsDownload, untried_reason
+from seampact.ir.https.printable_url import printable_url
+
+RELEASE_BASE_URL: Final = "https://github.com/jubasse/seampact/releases/download"
+DEADLINE_SECONDS: Final = 600.0
+BYTES_MAX: Final = 512 * 1024 * 1024
+
+_FETCH_FIX: Final = (
+    "Check that the URL serves the release asset over HTTPS, or set [tool.seampact.binary] in your root "
+    "pyproject.toml to a mirror `url` or a `path`, with their hashes."
+)
+
+_MIRROR_QUERY_OR_FRAGMENT: Final = (
+    "was not tried: the mirror base URL has a query or a fragment, so the asset name cannot be appended to its path"
+)
+
+
+class BinaryDownload:
+    def __init__(
+        self,
+        release_base_url: str = RELEASE_BASE_URL,
+        deadline_seconds: float = DEADLINE_SECONDS,
+        ca_file: str | None = None,
+    ) -> None:
+        """`ca_file` replaces the system's certificate authorities; tests serve the assets themselves."""
+        self._release_base_url = release_base_url
+        self._https = HttpsDownload(deadline_seconds, ca_file)
+
+    def release_url(self, version: str, asset: str) -> str:
+        """The URL of `asset` in the release of `version`, tagged `v<version>`."""
+        return f"{self._release_base_url}/v{quote(version, safe='')}/{asset}"
+
+    @staticmethod
+    def mirror_url(base_url: str, asset: str) -> str:
+        """Raises `binary.fetch-failed` for a base with a query or a fragment, which the asset would land in."""
+        if "?" in base_url or "#" in base_url:
+            raise _fetch_failed(base_url, _MIRROR_QUERY_OR_FRAGMENT)
+
+        return f"{base_url.rstrip('/')}/{asset}"
+
+    @staticmethod
+    def refuse_unless_https(url: str) -> None:
+        """Refuses a URL that is not `https:`, or holds a control character or a space, before the cache is touched.
+        Raises `binary.fetch-failed`."""
+        untried = untried_reason(url)
+
+        if untried is not None:
+            raise _fetch_failed(url, f"was not tried: {untried}")
+
+    def stream(self, url: str, sink: Callable[[bytes], None]) -> None:
+        """Streams the asset at `url` into `sink`. Raises `binary.fetch-failed`, or what the sink raises."""
+        failure = self._https.stream(url, BYTES_MAX, sink)
+
+        if failure is not None:
+            raise _fetch_failed(failure.url, failure.reason)
+
+
+def _fetch_failed(url: str, reason: str) -> BinaryRefusedError:
+    return BinaryRefusedError(
+        BinaryFailureCode.FETCH_FAILED,
+        f"Downloading the compiler binary from '{printable_url(url)}' {reason}; nothing is installed.",
+        _FETCH_FIX,
+    )

seampact_ir-1.0.0/src/seampact/ir/binary/failure.py

@@ -0,0 +1,38 @@
+"""The refusals of the compiler binary channel of a Python build (ADR 0010, "Amendment 2026-11-01: the Python
+channels"): the codes are those of the PHP and JVM channels."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class BinaryFailureCode(StrEnum):
+    UNPUBLISHED = "binary.unpublished"
+    PIN_MISSING = "binary.pin-missing"
+    PIN_INVALID = "binary.pin-invalid"
+    HASH_MISMATCH = "binary.hash-mismatch"
+    FETCH_FAILED = "binary.fetch-failed"
+    OVERRIDE_NOT_ROOT = "binary.override-not-root"
+    PLATFORM_UNSUPPORTED = "binary.platform-unsupported"
+    CACHE_UNAVAILABLE = "binary.cache-unavailable"
+    CACHE_UNSAFE = "binary.cache-unsafe"
+    COMPILE_REFUSED = "binary.compile-refused"
+    COMPILE_TIMEOUT = "binary.compile-timeout"
+    COMPILE_FAILED = "binary.compile-failed"
+    DOCUMENTS_REFUSED = "binary.documents-refused"
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryFailure:
+    """Why the compiler binary is not run: the code, what was found, and the fix."""
+
+    code: BinaryFailureCode
+    message: str
+    fix: str
+
+
+class BinaryRefusedError(Exception):
+    """The compiler binary is refused before or while it runs; `failure` names the code and the fix."""
+
+    def __init__(self, code: BinaryFailureCode, message: str, fix: str) -> None:
+        super().__init__(f"{code.value}: {message} {fix}")
+        self.failure = BinaryFailure(code, message, fix)

seampact_ir-1.0.0/src/seampact/ir/binary/host_libc.py

@@ -0,0 +1,39 @@
+"""The C library of a Linux host; other systems have none to tell apart."""
+
+import os
+from enum import StrEnum
+from typing import Final
+
+_MUSL_LOADER_PREFIX: Final = "ld-musl-"
+_LIBRARY_DIRECTORY: Final = "/lib"
+
+
+class HostLibc(StrEnum):
+    GLIBC = "glibc"
+    MUSL = "musl"
+    UNKNOWN = "unknown"
+    NONE = "none"
+
+
+def linux_libc(glibc_version: str | None, library_entries: list[str]) -> HostLibc:
+    """glibc when `os.confstr("CS_GNU_LIBC_VERSION")` answered (`glibc_version`); otherwise the loaders under `/lib`
+    decide: `ld-musl-*` is musl, anything else unknown."""
+    if glibc_version is not None:
+        return HostLibc.GLIBC
+
+    if any(entry.startswith(_MUSL_LOADER_PREFIX) for entry in library_entries):
+        return HostLibc.MUSL
+
+    return HostLibc.UNKNOWN
+
+
+def current_linux_libc() -> HostLibc:
+    return linux_libc(_glibc_version(), os.listdir(_LIBRARY_DIRECTORY) if os.path.isdir(_LIBRARY_DIRECTORY) else [])
+
+
+def _glibc_version() -> str | None:
+    try:
+        return os.confstr("CS_GNU_LIBC_VERSION")
+    except (ValueError, OSError):
+        # musl has no such name: the question has no answer there, and the loader decides.
+        return None