tensoracle 0.3.1__py3-none-any.whl

tensoracle/_execution.py

@@ -0,0 +1,184 @@
+"""Execute TensorRT engines with caller-owned addresses and CUDA streams."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Self
+
+import tensorrt as trt
+
+if TYPE_CHECKING:
+    from ._cache import EngineHandle
+
+
+class EngineExecution:
+    """One independent TensorRT context retained with its checked engine handle.
+
+    Use ``handle.create_execution()`` or construct this type with an ``EngineHandle``.
+    The caller owns buffers, streams, their ordering, and completion. This object
+    neither copies data nor synchronizes. Finish outstanding work before changing
+    shapes or streams, closing, or reusing the object from another thread.
+    """
+
+    def __init__(self, handle: EngineHandle) -> None:
+        self._handle: EngineHandle | None = handle
+        self._context: trt.IExecutionContext | None = None
+        self._ready = False
+        engine = handle.engine
+        self._names = tuple(engine.get_tensor_name(i) for i in range(engine.num_io_tensors))
+        self._ranges: dict[str, tuple[tuple[int, ...], tuple[int, ...]]] = {}
+        initial_shapes = {}
+        try:
+            for name in self._names:
+                if engine.get_tensor_location(name) != trt.TensorLocation.DEVICE:
+                    raise ValueError(
+                        f"tensor {name!r} has HOST location; execution requires DEVICE"
+                    )
+                if engine.get_tensor_mode(name) != trt.TensorIOMode.INPUT:
+                    continue
+                if engine.is_shape_inference_io(name):
+                    raise ValueError(f"input {name!r} is an external shape tensor; not supported")
+                shape = tuple(engine.get_tensor_shape(name))
+                if -1 in shape:
+                    low, optimum, high = (
+                        tuple(part) for part in engine.get_tensor_profile_shape(name, 0)
+                    )
+                    initial_shapes[name] = optimum
+                    if low != high:
+                        self._ranges[name] = (low, high)
+                else:
+                    initial_shapes[name] = shape
+            self._context = engine.create_execution_context()
+            if self._context is None:
+                raise RuntimeError("TensorRT failed to create an execution context")
+            # Probe output dimensions before accepting the engine. A ranged engine
+            # still requires an explicit caller setting after this capability check.
+            self._set_shapes(initial_shapes, creating=True)
+            self._ready = not self._ranges
+        except BaseException:
+            self.close()
+            raise
+
+    def set_input_shapes(self, shapes: Mapping[str, tuple[int, ...]]) -> None:
+        """Set every ranged input together, validating all shapes before TensorRT.
+
+        Fixed inputs, including single-point profiles, are initialized at creation
+        and omitted here. A TensorRT failure invalidates the setting until a complete
+        subsequent call succeeds; partial settings are not rolled back.
+        """
+        self._require_open()
+        self._check_names(shapes, self._ranges.keys(), "input shape")
+        for name, shape in shapes.items():
+            low, high = self._ranges[name]
+            if (
+                not isinstance(shape, tuple)
+                or len(shape) != len(low)
+                or any(
+                    type(value) is not int or not minimum <= value <= maximum
+                    for value, minimum, maximum in zip(shape, low, high, strict=True)
+                )
+            ):
+                raise ValueError(
+                    f"input {name!r} shape {shape!r} is outside range {low!r}..{high!r}"
+                )
+        self._set_shapes(shapes)
+
+    def get_tensor_shape(self, name: str) -> tuple[int, ...]:
+        """Read a concrete input or output shape after all input shapes are ready."""
+        context = self._require_ready()
+        self._check_tensor(name)
+        shape = tuple(context.get_tensor_shape(name))
+        if any(dimension < 0 for dimension in shape):
+            self._ready = False
+            raise RuntimeError(f"tensor {name!r} shape {shape!r} is unresolved")
+        return shape
+
+    def get_tensor_dtype(self, name: str) -> trt.DataType:
+        """Read a tensor's TensorRT dtype for allocating a caller-owned buffer."""
+        self._require_open()
+        self._check_tensor(name)
+        return self._handle.engine.get_tensor_dtype(name)
+
+    def enqueue(self, addresses: Mapping[str, int], *, stream: int) -> None:
+        """Enqueue all tensor addresses on the caller's stream without waiting.
+
+        Addresses must be positive integers, and the stream must be a nonnegative
+        integer (0 is the default stream). Bool is rejected. This method cannot
+        check buffer dtype, dimensions, layout, size, lifetime, or device selection.
+        """
+        self._require_open()
+        self._check_names(addresses, self._names, "address")
+        for name, address in addresses.items():
+            if type(address) is not int or address <= 0:
+                raise ValueError(f"tensor {name!r} address {address!r} must be a positive integer")
+        if type(stream) is not int or stream < 0:
+            raise ValueError(f"stream {stream!r} must be a nonnegative integer")
+        context = self._require_ready()
+        for name in self._names:
+            if not context.set_tensor_address(name, addresses[name]):
+                raise RuntimeError(f"TensorRT rejected tensor {name!r} address {addresses[name]!r}")
+        if not context.execute_async_v3(stream):
+            raise RuntimeError(f"TensorRT enqueue failed on stream {stream!r}")
+
+    def close(self) -> None:
+        """Release context before handle without synchronization; repeated calls do nothing.
+
+        The caller must confirm that all enqueued work has completed before closing.
+        """
+        self._ready = False
+        self._context = None
+        self._handle = None
+
+    def __enter__(self) -> Self:
+        self._require_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    def _require_open(self) -> trt.IExecutionContext:
+        if self._context is None:
+            raise RuntimeError("engine execution is closed")
+        return self._context
+
+    def _require_ready(self) -> trt.IExecutionContext:
+        context = self._require_open()
+        if not self._ready:
+            raise RuntimeError("input shapes need a complete successful setting before execution")
+        return context
+
+    def _check_tensor(self, name: str) -> None:
+        if name not in self._names:
+            raise ValueError(f"unknown engine tensor {name!r}")
+
+    @staticmethod
+    def _check_names(values: Mapping, names, field: str) -> None:
+        expected = set(names)
+        for name in sorted(expected - values.keys(), key=repr):
+            raise ValueError(f"tensor {name!r} {field} is missing")
+        for name in sorted(values.keys() - expected, key=repr):
+            raise ValueError(f"unexpected tensor {name!r} {field} {values[name]!r}")
+
+    def _set_shapes(self, shapes: Mapping[str, tuple[int, ...]], *, creating: bool = False) -> None:
+        self._ready = False
+        for name, shape in shapes.items():
+            try:
+                accepted = self._context.set_input_shape(name, shape)
+            except Exception as error:
+                raise RuntimeError(
+                    f"TensorRT failed to set input {name!r} shape {shape!r}"
+                ) from error
+            if not accepted:
+                raise RuntimeError(f"TensorRT rejected input {name!r} shape {shape!r}")
+        missing = self._context.infer_shapes()
+        if missing:
+            raise RuntimeError(f"TensorRT shape inference requires tensors {missing!r}")
+        for name in self._names:
+            shape = tuple(self._context.get_tensor_shape(name))
+            if any(dimension < 0 for dimension in shape):
+                if creating:
+                    raise ValueError(
+                        f"tensor {name!r} has data-dependent shape {shape!r}; not supported"
+                    )
+                raise RuntimeError(f"tensor {name!r} shape {shape!r} is unresolved")
+        self._ready = True

tensoracle/_memory.py

@@ -0,0 +1,18 @@
+"""Release unused host memory when the process allocator supports trimming."""
+
+import ctypes
+import ctypes.util
+
+
+def release_host_memory() -> None:
+    """Return free glibc heap pages without requiring libc on other platforms."""
+    try:
+        library = ctypes.util.find_library("c")
+        if library is None:
+            return
+        trim = ctypes.CDLL(library).malloc_trim
+        trim.argtypes = [ctypes.c_size_t]
+        trim.restype = ctypes.c_int
+        trim(0)
+    except (OSError, AttributeError):
+        pass

tensoracle/_plugins.py

@@ -0,0 +1,223 @@
+"""Validate native plugin exports and retain TensorRT library handles."""
+
+import hashlib
+import struct
+import sys
+import threading
+from collections.abc import Sequence
+from pathlib import Path
+
+
+class PluginLibraryError(ValueError):
+    """A native plugin library cannot be registered for this process."""
+
+
+_lock = threading.RLock()
+_loaded_paths: dict[Path, str] = {}
+_loaded_digests: dict[str, object] = {}
+
+
+def _read_struct(data: bytes, offset: int, format_: str) -> tuple[int, ...]:
+    size = struct.calcsize(format_)
+    if offset < 0 or offset + size > len(data):
+        raise PluginLibraryError("truncated native library")
+    return struct.unpack_from(format_, data, offset)
+
+
+def _elf_exports(data: bytes) -> set[str]:
+    if len(data) < 64 or data[:4] != b"\x7fELF":
+        raise PluginLibraryError("invalid ELF plugin library")
+    bits, encoding = data[4:6]
+    if bits not in (1, 2) or encoding not in (1, 2):
+        raise PluginLibraryError("unsupported ELF plugin library")
+    endian = "<" if encoding == 1 else ">"
+    if bits == 2:
+        (section_offset,) = _read_struct(data, 40, endian + "Q")
+        section_size, section_count = _read_struct(data, 58, endian + "HH")
+        section_format = endian + "IIQQQQIIQQ"
+        symbol_format = endian + "IBBHQQ"
+    else:
+        (section_offset,) = _read_struct(data, 32, endian + "I")
+        section_size, section_count = _read_struct(data, 46, endian + "HH")
+        section_format = endian + "IIIIIIIIII"
+        symbol_format = endian + "IIIBBH"
+    if section_count == 0 or section_size < struct.calcsize(section_format):
+        raise PluginLibraryError("missing ELF section table")
+    sections = [
+        _read_struct(data, section_offset + index * section_size, section_format)
+        for index in range(section_count)
+    ]
+    exports = set()
+    for section in sections:
+        if section[1] != 11:  # SHT_DYNSYM
+            continue
+        string_index = section[6]
+        if string_index >= len(sections):
+            raise PluginLibraryError("invalid ELF symbol string table")
+        strings = sections[string_index]
+        string_data = data[strings[4] : strings[4] + strings[5]]
+        if len(string_data) != strings[5]:
+            raise PluginLibraryError("truncated ELF symbol string table")
+        symbols_offset, symbols_size, symbol_stride = section[4], section[5], section[9]
+        if symbol_stride < struct.calcsize(symbol_format) or symbols_size % symbol_stride:
+            raise PluginLibraryError("invalid ELF symbol table")
+        for offset in range(symbols_offset, symbols_offset + symbols_size, symbol_stride):
+            symbol = _read_struct(data, offset, symbol_format)
+            name_offset = symbol[0]
+            if bits == 2:
+                info, visibility, section_index = symbol[1:4]
+            else:
+                info, visibility, section_index = symbol[3:6]
+            if section_index == 0 or info >> 4 not in (1, 2) or visibility & 3 not in (0, 3):
+                continue
+            if name_offset >= len(string_data):
+                raise PluginLibraryError("invalid ELF symbol name")
+            end = string_data.find(b"\0", name_offset)
+            if end < 0:
+                raise PluginLibraryError("unterminated ELF symbol name")
+            exports.add(string_data[name_offset:end].decode("ascii", errors="replace"))
+    return exports
+
+
+def _pe_export_offsets(data: bytes) -> dict[str, int]:
+    """Locate PE export values without executing any library initializers."""
+    if data[:2] != b"MZ":
+        raise PluginLibraryError("invalid PE plugin library")
+    (header,) = _read_struct(data, 0x3C, "<I")
+    if data[header : header + 4] != b"PE\0\0":
+        raise PluginLibraryError("invalid PE plugin library")
+    (section_count,) = _read_struct(data, header + 6, "<H")
+    (optional_size,) = _read_struct(data, header + 20, "<H")
+    optional = header + 24
+    (magic,) = _read_struct(data, optional, "<H")
+    if magic not in (0x10B, 0x20B):
+        raise PluginLibraryError("unsupported PE plugin library")
+    (export_rva,) = _read_struct(data, optional + (112 if magic == 0x20B else 96), "<I")
+    sections = [
+        _read_struct(data, optional + optional_size + index * 40 + 8, "<IIII")
+        for index in range(section_count)
+    ]
+
+    def file_offset(rva: int) -> int:
+        for virtual_size, virtual_address, raw_size, raw_offset in sections:
+            if virtual_address <= rva < virtual_address + max(virtual_size, raw_size):
+                return raw_offset + rva - virtual_address
+        raise PluginLibraryError("invalid PE export address")
+
+    if export_rva == 0:
+        return {}
+    export = file_offset(export_rva)
+    (count,) = _read_struct(data, export + 24, "<I")
+    functions_rva, names_rva, ordinals_rva = _read_struct(data, export + 28, "<III")
+    if count > 100_000:
+        raise PluginLibraryError("invalid PE export count")
+    names = {}
+    for index in range(count):
+        (name_rva,) = _read_struct(data, file_offset(names_rva) + index * 4, "<I")
+        offset = file_offset(name_rva)
+        end = data.find(b"\0", offset)
+        if end < 0:
+            raise PluginLibraryError("unterminated PE export name")
+        (ordinal,) = _read_struct(data, file_offset(ordinals_rva) + index * 2, "<H")
+        (value_rva,) = _read_struct(data, file_offset(functions_rva) + ordinal * 4, "<I")
+        names[data[offset:end].decode("ascii", errors="replace")] = file_offset(value_rva)
+    return names
+
+
+def _pe_exports(data: bytes) -> set[str]:
+    return set(_pe_export_offsets(data))
+
+
+def _exports(data: bytes) -> set[str]:
+    if sys.platform.startswith("linux"):
+        return _elf_exports(data)
+    if sys.platform == "win32":
+        return _pe_exports(data)
+    raise PluginLibraryError(f"native plugin inspection is unsupported on {sys.platform}")
+
+
+def exported_data(data: bytes, name: str, expected_size: int | None = None) -> bytes:
+    """Read an exported constant from a native library without loading the library."""
+    if sys.platform == "win32":
+        if expected_size is None or expected_size <= 0:
+            raise PluginLibraryError("PE data inspection requires a positive size")
+        offset = _pe_export_offsets(data).get(name)
+        if offset is None or offset + expected_size > len(data):
+            raise PluginLibraryError(f"native library does not export {name}")
+        return data[offset : offset + expected_size]
+    if sys.platform != "linux":
+        raise PluginLibraryError(f"native data inspection is unsupported on {sys.platform}")
+    if len(data) < 64 or data[:6] != b"\x7fELF\x02\x01":
+        raise PluginLibraryError("expected a 64-bit little-endian ELF plugin library")
+    (section_offset,) = _read_struct(data, 40, "<Q")
+    section_size, section_count = _read_struct(data, 58, "<HH")
+    if section_size < 64:
+        raise PluginLibraryError("invalid ELF section table")
+    sections = [
+        _read_struct(data, section_offset + index * section_size, "<IIQQQQIIQQ")
+        for index in range(section_count)
+    ]
+    for section in sections:
+        if section[1] != 11:
+            continue
+        if section[6] >= len(sections):
+            raise PluginLibraryError("invalid ELF symbol string table")
+        strings = sections[section[6]]
+        names = data[strings[4] : strings[4] + strings[5]]
+        stride = section[9]
+        if stride < 24:
+            raise PluginLibraryError("invalid ELF symbol stride")
+        for offset in range(section[4], section[4] + section[5], stride):
+            name_offset, _, _, section_index, address, size = _read_struct(data, offset, "<IBBHQQ")
+            if name_offset >= len(names) or section_index >= len(sections):
+                continue
+            end = names.find(b"\0", name_offset)
+            if end < 0 or names[name_offset:end] != name.encode("ascii"):
+                continue
+            owner = sections[section_index]
+            file_offset = owner[4] + address - owner[3]
+            if size <= 0 or file_offset < 0 or file_offset + size > len(data):
+                raise PluginLibraryError(f"invalid native data symbol {name}")
+            if expected_size is not None and expected_size != size:
+                raise PluginLibraryError(f"native data symbol {name} has the wrong size")
+            return data[file_offset : file_offset + size]
+    raise PluginLibraryError(f"native library does not export {name}")
+
+
+def register_libraries(paths: Sequence[Path]) -> tuple[str, ...]:
+    """Register each distinct library once and return the digests of its loaded bytes."""
+    import tensorrt as trt
+
+    digests = []
+    with _lock:
+        for candidate in paths:
+            try:
+                path = Path(candidate).resolve(strict=True)
+                data = path.read_bytes()
+            except OSError as error:
+                raise PluginLibraryError(
+                    f"plugin library is missing or unreadable: {candidate}"
+                ) from error
+            digest = hashlib.sha256(data).hexdigest()
+            if path in _loaded_paths:
+                if _loaded_paths[path] != digest:
+                    raise PluginLibraryError(f"loaded plugin library changed: {path}")
+                digests.append(digest)
+                continue
+            if "getCreators" not in _exports(data):
+                raise PluginLibraryError(f"plugin library does not export getCreators: {path}")
+            if digest not in _loaded_digests:
+                try:
+                    handle = trt.get_plugin_registry().load_library(str(path))
+                except Exception as error:
+                    raise PluginLibraryError(
+                        f"TensorRT could not register plugin library: {path}"
+                    ) from error
+                if handle is None:
+                    raise PluginLibraryError(f"TensorRT could not register plugin library: {path}")
+                if hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+                    raise PluginLibraryError(f"plugin library changed while loading: {path}")
+                _loaded_digests[digest] = handle
+            _loaded_paths[path] = digest
+            digests.append(digest)
+    return tuple(digests)

tensoracle/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
+
+__commit_id__ = commit_id = None

tensoracle/bundle.py

@@ -0,0 +1,206 @@
+"""Inspect a cubin bundle and its native plugin without a GPU or producer."""
+
+import hashlib
+import json
+import struct
+import tempfile
+from pathlib import Path
+from zipfile import ZipFile
+
+from ._plugins import PluginLibraryError, exported_data
+
+
+class BundleError(ValueError):
+    """A cubin bundle does not match its manifest or native plugin."""
+
+
+class MissingCubinError(BundleError):
+    """A declared cubin is missing."""
+
+
+class CorruptCubinError(BundleError):
+    """A cubin's bytes differ from its declared digest or length."""
+
+
+class CubinArchitectureError(BundleError):
+    """A cubin's ELF architecture differs from its declared SM."""
+
+
+class PluginBundleMismatchError(BundleError):
+    """A native plugin was built for a different cubin bundle."""
+
+
+def _canonical(value: object) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def bundle_sha256(manifest: dict) -> str:
+    """Return the identity of a manifest, excluding its own digest field."""
+    return hashlib.sha256(
+        _canonical({k: v for k, v in manifest.items() if k != "bundle_sha256"})
+    ).hexdigest()
+
+
+def cubin_sm(data: bytes) -> str:
+    """Read the NVIDIA architecture from a cubin ELF header."""
+    if len(data) < 64 or data[:6] != b"\x7fELF\x02\x01":
+        raise CubinArchitectureError("cubin is not a 64-bit little-endian ELF")
+    if struct.unpack_from("<H", data, 18)[0] != 190:
+        raise CubinArchitectureError("cubin has no NVIDIA CUDA ELF machine")
+    flags = struct.unpack_from("<I", data, 48)[0]
+    old_sm = (flags >> 16) & 0xFF
+    new_sm = (flags >> 8) & 0xFF
+    if old_sm in (86, 89):
+        return f"sm{old_sm}"
+    if new_sm == 120:
+        return "sm120"
+    raise CubinArchitectureError(f"unsupported cubin architecture in ELF flags: {flags:#x}")
+
+
+def _validate_entry(entry: dict) -> None:
+    if entry.get("target_sm") not in ("sm86", "sm89", "sm120"):
+        raise BundleError("unsupported target SM")
+    hidden = entry.get("hidden_trailing_parameters")
+    if hidden != [
+        {"name": "global_scratch", "parameter_bytes": 8},
+        {"name": "profile_scratch", "parameter_bytes": 8},
+    ]:
+        raise BundleError("unsupported hidden trailing parameters")
+    resources = entry.get("resources")
+    if not isinstance(resources, dict):
+        raise BundleError("missing cubin resources")
+    if resources.get("global_scratch_bytes") != 0 or resources.get("profile_scratch_bytes") != 0:
+        raise BundleError("nonzero scratch is unsupported")
+    for key in (
+        "compiled_shared_memory_bytes",
+        "launch_dynamic_shared_memory_bytes",
+        "registers_per_thread",
+    ):
+        if type(resources.get(key)) is not int or resources[key] < 0:
+            raise BundleError(f"invalid cubin resource {key}")
+    if resources["registers_per_thread"] == 0 or (
+        resources["launch_dynamic_shared_memory_bytes"] < resources["compiled_shared_memory_bytes"]
+    ):
+        raise BundleError("unsupported cubin resource range")
+    signature = entry.get("signature")
+    if (
+        not isinstance(entry.get("entry_symbol"), str)
+        or not entry["entry_symbol"]
+        or not isinstance(signature, list)
+    ):
+        raise BundleError("missing cubin symbol or signature")
+    if not 1 <= len(signature) <= 14:
+        raise BundleError("unsupported public argument count")
+    names = set()
+    for argument in signature:
+        if not isinstance(argument, dict) or not isinstance(argument.get("name"), str):
+            raise BundleError("invalid public argument")
+        if argument["name"] in names or argument.get("type") not in (
+            "*fp16",
+            "*fp32",
+            "*i8",
+            "*i32",
+            "i32",
+            "fp32",
+        ):
+            raise BundleError("unsupported public argument")
+        names.add(argument["name"])
+    specialization = entry.get("specialization")
+    if not isinstance(specialization, dict) or set(specialization) != {"divisible_by"}:
+        raise BundleError("unsupported specialization rule")
+    divisors = specialization["divisible_by"]
+    if not isinstance(divisors, dict) or any(
+        name not in names
+        or type(divisor) is not int
+        or divisor < 1
+        or divisor > (1 << 30)
+        or divisor & (divisor - 1)
+        for name, divisor in divisors.items()
+    ):
+        raise BundleError("unsupported specialization rule")
+    if any(
+        argument["type"] == "fp32" and divisors.get(argument["name"], 1) != 1
+        for argument in signature
+    ):
+        raise BundleError("unsupported floating point specialization rule")
+
+
+def inspect_bundle(root: Path, *, plugin: Path | None = None) -> str:
+    """Verify cubin bytes, ELF SM, supported launch metadata, and plugin identity."""
+    root = Path(root)
+    manifest = json.loads((root / "bundle.json").read_text(encoding="utf-8"))
+    if not isinstance(manifest, dict) or manifest.get("schema_version") != 1:
+        raise BundleError("unsupported bundle manifest")
+    entries = manifest.get("entries")
+    if not isinstance(entries, list) or not entries:
+        raise BundleError("bundle has no cubin entries")
+    digest = bundle_sha256(manifest)
+    if "bundle_sha256" in manifest and manifest["bundle_sha256"] != digest:
+        raise BundleError("bundle manifest digest differs")
+    visited = set()
+    cubins = {}
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise BundleError("invalid cubin entry")
+        _validate_entry(entry)
+        name = entry.get("file")
+        if not isinstance(name, str) or Path(name).is_absolute() or ".." in Path(name).parts:
+            raise BundleError("invalid cubin path")
+        if name in visited:
+            raise BundleError("duplicate cubin path")
+        visited.add(name)
+        path = root / name
+        if not path.is_file():
+            raise MissingCubinError(f"missing cubin: {path}")
+        data = path.read_bytes()
+        if len(data) != entry.get("bytes") or hashlib.sha256(data).hexdigest() != entry.get(
+            "sha256"
+        ):
+            raise CorruptCubinError(f"cubin digest or size differs: {path}")
+        actual_sm = cubin_sm(data)
+        if actual_sm != entry["target_sm"]:
+            raise CubinArchitectureError(
+                f"cubin {path} declares {entry['target_sm']} but ELF contains {actual_sm}"
+            )
+        if "embedded_symbol" in entry:
+            cubins[entry["embedded_symbol"]] = data
+    if plugin is not None:
+        try:
+            library = Path(plugin).read_bytes()
+            embedded = exported_data(library, "tensoracle_bundle_sha256", 65)
+        except (OSError, PluginLibraryError) as error:
+            raise PluginBundleMismatchError(
+                f"plugin bundle identity is unavailable: {plugin}"
+            ) from error
+        if embedded.rstrip(b"\0") != digest.encode("ascii"):
+            raise PluginBundleMismatchError(f"plugin and cubin bundle differ: {plugin}")
+        for symbol, data in cubins.items():
+            try:
+                native = exported_data(library, symbol, len(data))
+            except PluginLibraryError as error:
+                raise PluginBundleMismatchError(f"plugin lacks embedded cubin {symbol}") from error
+            if native != data:
+                raise PluginBundleMismatchError(f"plugin embedded cubin differs: {symbol}")
+    return digest
+
+
+def inspect_wheel(path: Path, *, plugin: str | None = None) -> str:
+    """Inspect the one cubin bundle inside a wheel without installing it."""
+    with tempfile.TemporaryDirectory() as directory, ZipFile(path) as archive:
+        root = Path(directory)
+        for info in archive.infolist():
+            member = Path(info.filename)
+            if member.is_absolute() or ".." in member.parts:
+                raise BundleError("wheel contains an invalid path")
+            if info.is_dir():
+                continue
+            destination = root / member
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            destination.write_bytes(archive.read(info))
+        manifests = list(root.rglob("bundle.json"))
+        if len(manifests) != 1:
+            raise BundleError("wheel must contain exactly one cubin bundle")
+        library = root / plugin if plugin is not None else None
+        if library is not None and (Path(plugin).is_absolute() or ".." in Path(plugin).parts):
+            raise BundleError("invalid plugin path in wheel")
+        return inspect_bundle(manifests[0].parent, plugin=library)