mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/sources/catalog/neural.py

@@ -0,0 +1,1618 @@
+"""Governed, offline encoding from one explicit local neural-model sidecar.
+
+This module is reachable only through ``embedding.resolve_local_neural_backend``. It has no model
+root default and no download, cache, hub, plugin, socket, or arbitrary command-execution path.
+Resolution captures regular files through one no-follow directory descriptor, verifies the exact
+PIN and every member, then closes the descriptor. Resolution prepares one authenticated private
+runtime worker so the per-item encode budget covers only inference.
+
+Provider-scale callers use ``encode_many``, which is the shared bounded seam and not a second
+encoder: it evaluates at most 1000 items serially through the ``encode`` below. Every nonempty
+item returns the model-produced vector the three installed-wheel receipts authenticated for
+that exact tuple; an empty item returns the descriptor-sized deterministic no-signal value
+without inference. Every declared tuple runs this one adapter. The PIN's ``max_batch`` budget
+is recorded and unrouted.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import csv
+import hashlib
+import io
+import multiprocessing
+import os
+import platform
+import resource
+import shutil
+import stat
+import sys
+import sysconfig
+import tempfile
+from collections import deque
+from importlib import metadata
+from importlib.machinery import BuiltinImporter, FrozenImporter, PathFinder
+from importlib.util import module_from_spec
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, parse_json
+from mostlyright.data_harness.sources.catalog.embedding import (
+    BOUNDED_SCALAR_ADAPTER,
+    BatchEncodeResult,
+    PinnedLocalBackendDescriptor,
+    encode_many_bounded,
+)
+from mostlyright.data_harness.sources.contracts import SourceContractError
+
+PIN_NAME = "PIN.json"
+PIN_SHA256 = "42b5a7c9ff04b1ff306e35a711e4b937d50d286a3e62285a09a8e72bd479522a"
+COORDINATE_SHA256 = "efb1bb9a47444ce60e0758041c027e51e419c01dd03797643b773d3f18e88510"
+PIN_SCHEMA_VERSION = "local-search-neural-pin.v2"
+BACKEND_ID = "minilm_l6_v2_local"
+BACKEND_VERSION = "1.0.0"
+DIMENSIONS = 384
+QUANTIZATION = "int32_fixed_point_10000"
+RUNTIME_VERSIONS = {"onnxruntime": "1.28.0", "tokenizers": "0.23.1"}
+SUPPORTED_TUPLES = frozenset(
+    {
+        "macos-14-arm64-cpython-3.13.12",
+        "macos-15-arm64-cpython-3.13.12",
+        "ubuntu-24.04-x86_64-cpython-3.13.14",
+    }
+)
+MAX_PIN_BYTES = 512 * 1024
+MAX_MODEL_BYTES = 128 * 1024 * 1024
+MAX_TEXT_CHARS = 4_096
+MAX_LENGTH = 256
+VECTOR_SCALE = 10_000
+MAX_ENCODE_LATENCY_NS = 2_000_000_000
+MAX_PEAK_RSS_BYTES = 768 * 1024 * 1024
+MAX_RUNTIME_INITIALIZATION_SECONDS = 15.0
+
+#: The mode every declared tuple runs in, and the only one this module has evidence for.
+BATCH_ADAPTER_MODE = BOUNDED_SCALAR_ADAPTER
+
+#: The native batch width authenticated by the exact PIN (``budgets.max_batch``). It is recorded
+#: and never read. Routing it would mean padding a group of texts to a common shape and running one
+#: fused inference, and the vectors that came back would be a different computation from the
+#: ones the installed-wheel receipts authenticated -- a claim the recorded measurements do not
+#: support.
+#: This constant records an unexercised budget and is not routed by the production adapter.
+NATIVE_MAX_BATCH = 32
+_INT32_MIN = -(1 << 31)
+_INT32_MAX = (1 << 31) - 1
+_WORKER_JOIN_SECONDS = 0.1
+_RUNTIME_ROOT_DISTRIBUTIONS = (
+    "onnxruntime",
+    "tokenizers",
+)
+
+# Capture interpreter-owned roots before an authenticated runtime finder is installed. Calling
+# ``sysconfig`` from inside the finder would itself perform imports on a cold interpreter and hand
+# those imports to the very meta-path hooks the finder is designed not to trust.
+_STDLIB_ROOTS = frozenset(
+    Path(value).resolve(strict=True)
+    for key in ("stdlib", "platstdlib")
+    if isinstance((value := sysconfig.get_path(key)), str)
+)
+_THIRD_PARTY_ROOTS = frozenset(
+    Path(value).resolve(strict=True)
+    for key in ("purelib", "platlib")
+    if isinstance((value := sysconfig.get_path(key)), str)
+)
+
+
+class LocalNeuralEmbeddingBackend:
+    """A private-session embedding backend bound to captured, verified sidecar bytes."""
+
+    def __init__(
+        self,
+        descriptor: PinnedLocalBackendDescriptor,
+        *,
+        model_bytes: bytes,
+        tokenizer_bytes: bytes,
+        runtime_closure_sha256: str,
+    ) -> None:
+        self._descriptor = descriptor
+        self._model_bytes = model_bytes
+        self._tokenizer_bytes = tokenizer_bytes
+        self._runtime_closure_sha256 = runtime_closure_sha256
+        self._worker: tuple[Any, ...] | None = None
+
+    @property
+    def descriptor(self) -> PinnedLocalBackendDescriptor:
+        return self._descriptor
+
+    def encode(self, text: str) -> tuple[int, ...]:
+        if not isinstance(text, str) or len(text) > MAX_TEXT_CHARS:
+            raise SourceContractError(
+                "NEURAL_INPUT_LIMIT",
+                "embedding.text",
+                f"must be a string containing 0 to {MAX_TEXT_CHARS} characters",
+            )
+        if not text:
+            # A valid catalog entry may have no published column or vocabulary facts. The lexical
+            # backend represents that absence as a zero vector; preserve the same no-signal
+            # meaning here without starting the model worker merely to encode no text.
+            return (0,) * self._descriptor.dimensions
+
+        connection, process = self._ensure_worker()[:2]
+        try:
+            connection.send(("encode", text))
+        except (BrokenPipeError, EOFError, OSError):
+            self._stop_worker()
+            raise SourceContractError(
+                "NEURAL_SESSION_UNAVAILABLE",
+                "embedding.runtime",
+                "the bounded neural worker became unavailable",
+            ) from None
+        try:
+            response = _receive_worker_result(
+                connection,
+                process,
+                timeout_seconds=MAX_ENCODE_LATENCY_NS / 1_000_000_000,
+                snapshot_root=self._worker[2] if len(self._worker) > 2 else None,
+            )
+        except SourceContractError:
+            self._worker = None
+            raise
+        if response.get("status") == "error":
+            self._stop_worker()
+            raise SourceContractError(
+                response.get("code", "NEURAL_SESSION_UNAVAILABLE"),
+                response.get("path", "embedding.runtime"),
+                response.get("detail", "the bounded neural worker failed"),
+            )
+        if set(response) != {"status", "vector", "peak_rss_bytes"} or response["status"] != "ok":
+            self._stop_worker()
+            raise SourceContractError(
+                "NEURAL_SESSION_UNAVAILABLE",
+                "embedding.runtime",
+                "the bounded neural worker returned an invalid response",
+            )
+        result = tuple(response["vector"])
+        if len(result) != DIMENSIONS or any(
+            type(value) is not int or not _INT32_MIN <= value <= _INT32_MAX for value in result
+        ):
+            self._stop_worker()
+            raise SourceContractError(
+                "NEURAL_VECTOR_DIMENSIONS",
+                "embedding.vector",
+                f"quantized output must contain exactly {DIMENSIONS} signed int32 integers",
+            )
+        if type(response["peak_rss_bytes"]) is not int or response["peak_rss_bytes"] > (
+            MAX_PEAK_RSS_BYTES
+        ):
+            self._stop_worker()
+            raise SourceContractError(
+                "NEURAL_MEMORY_LIMIT",
+                "embedding.runtime",
+                "encoding exceeded the pinned peak-memory limit",
+            )
+        return result
+
+    def encode_many(self, texts: tuple[str, ...] | list[str]) -> BatchEncodeResult:
+        """Encode a bounded sequence serially through this backend's exact scalar operation.
+
+        There is no second batch code path here on purpose. Each item goes through ``encode``
+        above. Nonempty items use the same bounded request to the same private worker, the same PIN
+        and installed-closure checks, the same 256-token truncation, mean pooling, normalization
+        and integer quantization, the same deadline, and the same terminate/kill on a worker that
+        does not answer. Empty items return the deterministic descriptor-sized zero defined by the
+        scalar operation and start no inference. Thus each batch vector is exactly its scalar
+        vector on every declared tuple.
+
+        Provider-scale publication has a measured 34--44 CPU-hour projection. The seam makes
+        capability claims only for the tuples authenticated by installed-wheel receipts.
+        """
+
+        return encode_many_bounded(self, texts)
+
+    def _ensure_worker(self) -> tuple[Any, ...]:
+        if self._worker is None:
+            self._worker = _start_worker(
+                self._model_bytes,
+                self._tokenizer_bytes,
+                self._runtime_closure_sha256,
+            )
+        return self._worker
+
+    def _stop_worker(self) -> None:
+        if self._worker is None:
+            return
+        worker = self._worker
+        self._worker = None
+        _terminate_worker(*worker)
+
+    def close(self) -> None:
+        """Stop the private bounded inference worker, if it was started."""
+
+        self._stop_worker()
+
+    def __del__(self) -> None:
+        try:
+            self._stop_worker()
+        except Exception:
+            pass
+
+
+def resolve_local_neural_backend(
+    model_root: str | os.PathLike[str] | None,
+) -> LocalNeuralEmbeddingBackend:
+    """Capture one explicit sidecar and prepare its authenticated local runtime."""
+
+    path = _explicit_absolute_root(model_root)
+    pin, members = _capture_sidecar(path)
+    tuple_id = _runtime_tuple()
+    supported = pin.get("supported_tuples")
+    if (
+        tuple_id not in SUPPORTED_TUPLES
+        or supported != sorted(SUPPORTED_TUPLES)
+        or tuple_id not in supported
+    ):
+        raise SourceContractError(
+            "NEURAL_TUPLE_UNAVAILABLE",
+            "embedding.runtime_tuple",
+            f"runtime tuple {tuple_id!r} is not supported by the exact PIN",
+        )
+
+    runtime_closures = pin.get("runtime_closures")
+    if not isinstance(runtime_closures, dict) or set(runtime_closures) != set(supported):
+        raise SourceContractError(
+            "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+            "embedding.runtime",
+            "the supported tuple registry has no exact installed-runtime closure",
+        )
+    runtime_closure_sha256 = runtime_closures.get(tuple_id)
+    if not _is_sha256(runtime_closure_sha256):
+        raise SourceContractError(
+            "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+            "embedding.runtime",
+            "the runtime closure coordinate for this tuple is invalid",
+        )
+    artifacts = tuple(sorted((item["path"], item["sha256"]) for item in pin["artifacts"]))
+    descriptor = PinnedLocalBackendDescriptor(
+        backend_id=BACKEND_ID,
+        backend_version=BACKEND_VERSION,
+        dimensions=DIMENSIONS,
+        quantization=QUANTIZATION,
+        query_safe=False,
+        model_root=str(path),
+        pin_sha256=PIN_SHA256,
+        coordinate_sha256=COORDINATE_SHA256,
+        runtime_tuple=tuple_id,
+        runtime_closure_sha256=runtime_closure_sha256,
+        artifact_sha256s=artifacts,
+    )
+    backend = LocalNeuralEmbeddingBackend(
+        descriptor,
+        model_bytes=members["model.int8.onnx"],
+        tokenizer_bytes=members["tokenizer.json"],
+        runtime_closure_sha256=runtime_closure_sha256,
+    )
+    backend._ensure_worker()
+    return backend
+
+
+def _explicit_absolute_root(model_root: str | os.PathLike[str] | None) -> Path:
+    if model_root is None or isinstance(model_root, bytes):
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_REQUIRED",
+            "embedding.model_root",
+            "the caller must supply one explicit sidecar root",
+        )
+    try:
+        path = Path(os.fspath(model_root))
+    except TypeError:
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_REQUIRED",
+            "embedding.model_root",
+            "the caller must supply one explicit sidecar root",
+        ) from None
+    if not path.is_absolute():
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_ABSOLUTE",
+            "embedding.model_root",
+            "the caller-supplied sidecar root must be absolute",
+        )
+    return path
+
+
+def _capture_sidecar(root: Path) -> tuple[dict[str, Any], dict[str, bytes]]:
+    try:
+        initial = os.lstat(root)
+    except OSError:
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_UNAVAILABLE",
+            "embedding.model_root",
+            "the explicit sidecar root is unavailable",
+        ) from None
+    if stat.S_ISLNK(initial.st_mode):
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_LINK",
+            "embedding.model_root",
+            "the explicit sidecar root may not be a symbolic link",
+        )
+    if not stat.S_ISDIR(initial.st_mode):
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_UNAVAILABLE",
+            "embedding.model_root",
+            "the explicit sidecar root must be a directory",
+        )
+
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        root_fd = os.open(root, flags)
+    except OSError:
+        raise SourceContractError(
+            "NEURAL_MODEL_ROOT_UNAVAILABLE",
+            "embedding.model_root",
+            "the explicit sidecar root could not be descriptor-captured",
+        ) from None
+    try:
+        captured = os.fstat(root_fd)
+        if _identity(initial) != _identity(captured):
+            _root_race()
+        pin_bytes = _read_member(root_fd, PIN_NAME, MAX_PIN_BYTES)
+        if hashlib.sha256(pin_bytes).hexdigest() != PIN_SHA256:
+            raise SourceContractError(
+                "NEURAL_PIN_MISMATCH",
+                "embedding.model_root/PIN.json",
+                "PIN.json bytes differ from the selected coordinate",
+            )
+        pin = _parse_exact_pin(pin_bytes)
+        expected = {item["path"]: item["sha256"] for item in pin["artifacts"]}
+        if set(os.listdir(root_fd)) != {PIN_NAME, *expected}:
+            raise SourceContractError(
+                "NEURAL_MODEL_CLOSURE",
+                "embedding.model_root",
+                "the sidecar contains an absent or unpinned member",
+            )
+        members: dict[str, bytes] = {}
+        total = 0
+        for name in sorted(expected):
+            value = _read_member(root_fd, name, MAX_MODEL_BYTES)
+            total += len(value)
+            if total > MAX_MODEL_BYTES:
+                raise SourceContractError(
+                    "NEURAL_MODEL_BYTES",
+                    "embedding.model_root",
+                    "the sidecar exceeds its pinned byte limit",
+                )
+            if hashlib.sha256(value).hexdigest() != expected[name]:
+                raise SourceContractError(
+                    "NEURAL_ARTIFACT_MISMATCH",
+                    f"embedding.model_root/{name}",
+                    "artifact bytes differ from PIN.json",
+                )
+            members[name] = value
+        final_captured = os.fstat(root_fd)
+        try:
+            final = os.lstat(root)
+        except OSError:
+            _root_race()
+        if (
+            _identity(initial) != _identity(final)
+            or _identity(captured) != _identity(final_captured)
+            or _identity(captured) != _identity(final)
+            or captured.st_mtime_ns != final_captured.st_mtime_ns
+            or captured.st_ctime_ns != final_captured.st_ctime_ns
+            or set(os.listdir(root_fd)) != {PIN_NAME, *expected}
+        ):
+            _root_race()
+        return pin, members
+    finally:
+        os.close(root_fd)
+
+
+def _parse_exact_pin(value: bytes) -> dict[str, Any]:
+    try:
+        pin = parse_json(value)
+    except ValueError:
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "PIN.json is not strict JSON",
+        ) from None
+    if not isinstance(pin, dict) or pin.get("schema_version") != PIN_SCHEMA_VERSION:
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "PIN.json schema differs from the selected coordinate",
+        )
+    if pin.get("runtime") != RUNTIME_VERSIONS:
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "runtime pins differ from the selected coordinate",
+        )
+    if pin.get("tuple_candidates") != sorted(SUPPORTED_TUPLES):
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "runtime tuple candidates differ from the exact coordinate",
+        )
+    supported = pin.get("supported_tuples")
+    runtime_closures = pin.get("runtime_closures")
+    if (
+        not isinstance(supported, list)
+        or supported != sorted(supported)
+        or not set(supported).issubset(SUPPORTED_TUPLES)
+        or not isinstance(runtime_closures, dict)
+        or set(runtime_closures) != set(supported)
+        or any(not _is_sha256(digest) for digest in runtime_closures.values())
+    ):
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "supported tuples and installed-runtime closures are not an exact registry",
+        )
+    coordinate = pin.get("coordinate")
+    if not isinstance(coordinate, dict) or (
+        hashlib.sha256(canonical_json_bytes(coordinate)).hexdigest() != COORDINATE_SHA256
+    ):
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "model coordinate differs from the selected coordinate",
+        )
+    if coordinate.get("backend_id") != BACKEND_ID or coordinate.get("backend_version") != (
+        BACKEND_VERSION
+    ):
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "backend identity differs from the selected coordinate",
+        )
+    if coordinate.get("dimensions") != DIMENSIONS:
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "embedding dimensions differ from the selected coordinate",
+        )
+    artifacts = pin.get("artifacts")
+    if not isinstance(artifacts, list) or not artifacts:
+        raise SourceContractError(
+            "NEURAL_PIN_MISMATCH",
+            "embedding.model_root/PIN.json",
+            "the exact artifact coordinate is absent",
+        )
+    return pin
+
+
+def _read_member(root_fd: int, name: str, maximum: int) -> bytes:
+    if not name or "/" in name or "\\" in name or name in {".", ".."}:
+        raise SourceContractError(
+            "NEURAL_ARTIFACT_UNSAFE",
+            f"embedding.model_root/{name}",
+            "artifact name is unsafe",
+        )
+    try:
+        before = os.stat(name, dir_fd=root_fd, follow_symlinks=False)
+    except OSError:
+        raise SourceContractError(
+            "NEURAL_ARTIFACT_UNSAFE",
+            f"embedding.model_root/{name}",
+            "artifact is absent or unreadable",
+        ) from None
+    if not stat.S_ISREG(before.st_mode) or not 0 < before.st_size <= maximum:
+        raise SourceContractError(
+            "NEURAL_ARTIFACT_UNSAFE",
+            f"embedding.model_root/{name}",
+            "artifact must be a bounded regular file",
+        )
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(name, flags, dir_fd=root_fd)
+    except OSError:
+        raise SourceContractError(
+            "NEURAL_ARTIFACT_UNSAFE",
+            f"embedding.model_root/{name}",
+            "artifact could not be descriptor-captured without following links",
+        ) from None
+    try:
+        captured = os.fstat(descriptor)
+        if _identity(before) != _identity(captured) or before.st_size != captured.st_size:
+            raise SourceContractError(
+                "NEURAL_ARTIFACT_RACE",
+                f"embedding.model_root/{name}",
+                "artifact changed during descriptor capture",
+            )
+        chunks: list[bytes] = []
+        remaining = maximum + 1
+        while remaining:
+            chunk = os.read(descriptor, min(1024 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        value = b"".join(chunks)
+        after = os.fstat(descriptor)
+        if (
+            _identity(captured) != _identity(after)
+            or captured.st_size != after.st_size
+            or len(value) != captured.st_size
+            or len(value) > maximum
+        ):
+            raise SourceContractError(
+                "NEURAL_ARTIFACT_RACE",
+                f"embedding.model_root/{name}",
+                "artifact changed while it was read",
+            )
+        return value
+    finally:
+        os.close(descriptor)
+
+
+def _identity(value: os.stat_result) -> tuple[int, int]:
+    return value.st_dev, value.st_ino
+
+
+def _root_race() -> None:
+    raise SourceContractError(
+        "NEURAL_MODEL_ROOT_RACE",
+        "embedding.model_root",
+        "the caller-supplied sidecar root changed during descriptor capture",
+    )
+
+
+def _runtime_tuple() -> str:
+    machine = {"aarch64": "arm64", "amd64": "x86_64"}.get(
+        platform.machine().lower(), platform.machine().lower()
+    )
+    implementation = platform.python_implementation().lower()
+    version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    if sys.platform == "darwin":
+        macos_release = platform.mac_ver()[0].split(".", 1)[0] or "unknown"
+        os_coordinate = f"macos-{macos_release}"
+    elif sys.platform == "linux":
+        try:
+            release = platform.freedesktop_os_release()
+        except OSError:
+            release = {}
+        distribution = release.get("ID", "linux").lower()
+        os_version = release.get("VERSION_ID", "unknown").lower()
+        os_coordinate = f"{distribution}-{os_version}"
+    else:
+        os_coordinate = sys.platform.lower()
+    return f"{os_coordinate}-{machine}-{implementation}-{version}"
+
+
+def _is_sha256(value: object) -> bool:
+    if not isinstance(value, str) or len(value) != 64:
+        return False
+    try:
+        int(value, 16)
+    except ValueError:
+        return False
+    return value == value.lower()
+
+
+def _installed_runtime_closure_with_distributions() -> tuple[dict[str, Any], dict[str, Any]]:
+    distributions: dict[str, list[Any]] = {}
+    for distribution in metadata.distributions():
+        name = distribution.metadata.get("Name")
+        if isinstance(name, str):
+            distributions.setdefault(canonicalize_name(name), []).append(distribution)
+
+    pending: deque[tuple[str, str]] = deque(
+        (canonicalize_name(name), "") for name in _RUNTIME_ROOT_DISTRIBUTIONS
+    )
+    seen: set[str] = set()
+    selected: dict[str, Any] = {}
+    records: list[dict[str, str]] = []
+    while pending:
+        name, selected_extra = pending.popleft()
+        if name in seen:
+            continue
+        candidates = distributions.get(name, [])
+        if not candidates:
+            raise SourceContractError(
+                "NEURAL_RUNTIME_UNAVAILABLE",
+                "embedding.runtime",
+                f"required runtime distribution {name} is not installed",
+            )
+        if len(candidates) != 1:
+            raise _runtime_closure_refused(
+                f"required runtime distribution {name} is installed more than once"
+            )
+        distribution = candidates[0]
+        selected[name] = distribution
+        record = distribution.read_text("RECORD")
+        if record is None:
+            raise SourceContractError(
+                "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+                "embedding.runtime",
+                f"required runtime distribution {name} has no installed RECORD",
+            )
+        records.append(
+            {
+                "name": name,
+                "record_sha256": _portable_record_sha256(distribution, record),
+                "version": distribution.version,
+            }
+        )
+        seen.add(name)
+        for raw_requirement in distribution.requires or ():
+            requirement = Requirement(raw_requirement)
+            if requirement.marker is not None and not requirement.marker.evaluate(
+                {"extra": selected_extra}
+            ):
+                continue
+            pending.append((canonicalize_name(requirement.name), ""))
+    return (
+        {
+            "distributions": sorted(records, key=lambda item: item["name"]),
+            "roots": list(_RUNTIME_ROOT_DISTRIBUTIONS),
+            "schema_version": "local-search-neural-installed-closure.v2",
+        },
+        selected,
+    )
+
+
+def _installed_runtime_closure() -> dict[str, Any]:
+    closure, _distributions = _installed_runtime_closure_with_distributions()
+    return closure
+
+
+_INSTALLER_OWNED_RECORD_MEMBERS = frozenset({"INSTALLER", "REQUESTED", "direct_url.json", "RECORD"})
+_MAX_RUNTIME_MEMBER_BYTES = 512 * 1024 * 1024
+_MAX_RUNTIME_CLOSURE_BYTES = 2 * 1024 * 1024 * 1024
+
+
+class _SnapshotDistribution:
+    def __init__(self, source: Any, root: Path, record: str) -> None:
+        self.metadata = source.metadata
+        self.version = source.version
+        self.requires = source.requires
+        self.files = source.files
+        self._root = root
+        self._record = record
+
+    def locate_file(self, _path: str) -> Path:
+        return self._root
+
+    def read_text(self, name: str) -> str | None:
+        return self._record if name == "RECORD" else None
+
+
+def _runtime_closure_refused(detail: str) -> SourceContractError:
+    return SourceContractError("NEURAL_RUNTIME_CLOSURE_MISMATCH", "embedding.runtime", detail)
+
+
+def _record_digest(value: str) -> bytes:
+    if not value.startswith("sha256="):
+        raise ValueError
+    encoded = value.removeprefix("sha256=")
+    if len(encoded) != 43 or any(
+        character not in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+        for character in encoded
+    ):
+        raise ValueError
+    try:
+        decoded = base64.b64decode(encoded + "=", altchars=b"-_", validate=True)
+    except (binascii.Error, ValueError):
+        raise ValueError from None
+    if len(decoded) != hashlib.sha256().digest_size:
+        raise ValueError
+    return decoded
+
+
+def _read_runtime_member(
+    root_fd: int, parts: tuple[str, ...], expected_size: int, *, capture: bool = False
+) -> tuple[bytes, tuple[int, int, int, int], bytes | None]:
+    if expected_size > _MAX_RUNTIME_MEMBER_BYTES:
+        raise _runtime_closure_refused("a runtime member exceeds the closure byte limit")
+    directory_fd = os.dup(root_fd)
+    member_fd: int | None = None
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_CLOEXEC", 0)
+    try:
+        for part in parts[:-1]:
+            next_fd = os.open(part, flags | getattr(os, "O_DIRECTORY", 0), dir_fd=directory_fd)
+            os.close(directory_fd)
+            directory_fd = next_fd
+        member_fd = os.open(parts[-1], flags, dir_fd=directory_fd)
+        opened = os.fstat(member_fd)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_size != expected_size:
+            raise _runtime_closure_refused("a runtime member differs from its installed RECORD")
+        digest = hashlib.sha256()
+        captured: list[bytes] = []
+        total = 0
+        while True:
+            chunk = os.read(member_fd, min(1024 * 1024, expected_size - total + 1))
+            if not chunk:
+                break
+            total += len(chunk)
+            if total > expected_size:
+                raise _runtime_closure_refused("a runtime member differs from its installed RECORD")
+            digest.update(chunk)
+            if capture:
+                captured.append(chunk)
+        closed = os.fstat(member_fd)
+        if total != expected_size or (
+            opened.st_dev,
+            opened.st_ino,
+            opened.st_size,
+            opened.st_mtime_ns,
+        ) != (closed.st_dev, closed.st_ino, closed.st_size, closed.st_mtime_ns):
+            raise _runtime_closure_refused("a runtime member changed while it was authenticated")
+        fingerprint = (
+            closed.st_dev,
+            closed.st_ino,
+            closed.st_size,
+            closed.st_mtime_ns,
+        )
+        return digest.digest(), fingerprint, b"".join(captured) if capture else None
+    except OSError:
+        raise _runtime_closure_refused(
+            "a runtime member could not be opened without links"
+        ) from None
+    finally:
+        if member_fd is not None:
+            os.close(member_fd)
+        os.close(directory_fd)
+
+
+def _portable_record_binding(
+    distribution: Any, record: str
+) -> tuple[str, tuple[tuple[str, int, int, int, int], ...]]:
+    """Bind installed wheel payloads without binding the virtual-environment path.
+
+    Installers rewrite console-script shebangs with the destination interpreter and add a small
+    set of installer-owned metadata files. Neither can affect neural inference, while hashing them
+    makes the same wheel closure differ solely because it was installed at another absolute path.
+    All wheel-owned package and metadata rows remain bound exactly as installed.
+    """
+
+    parsed_rows: list[tuple[str, str, str]] = []
+    try:
+        parsed = csv.reader(io.StringIO(record, newline=""))
+        for row in parsed:
+            if len(row) != 3:
+                raise ValueError
+            parsed_rows.append((row[0], row[1], row[2]))
+    except (csv.Error, ValueError):
+        raise _runtime_closure_refused(
+            "a required runtime distribution has an invalid RECORD"
+        ) from None
+
+    record_rows = [
+        path
+        for path, digest, size in parsed_rows
+        if path.endswith(".dist-info/RECORD") and digest == size == ""
+    ]
+    if len(record_rows) != 1:
+        raise _runtime_closure_refused("a required runtime distribution has an invalid RECORD row")
+    dist_info = record_rows[0].rsplit("/", 1)[0]
+    rows: list[dict[str, str]] = []
+    fingerprints: list[tuple[str, int, int, int, int]] = []
+    seen_paths: set[str] = set()
+    total_bytes = 0
+    root = Path(distribution.locate_file(""))
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        root_fd = os.open(root, flags)
+    except OSError:
+        raise _runtime_closure_refused(
+            "the runtime installation root could not be opened"
+        ) from None
+    try:
+        for path, digest, size in parsed_rows:
+            if not path or path in seen_paths or "\\" in path or "\x00" in path:
+                raise _runtime_closure_refused("a required runtime RECORD path is invalid")
+            seen_paths.add(path)
+            pure = PurePosixPath(path)
+            parts = pure.parts
+            is_script = (
+                len(parts) == 5
+                and parts[:4] == ("..", "..", "..", "bin")
+                and parts[4] not in {"", ".", ".."}
+                and "/" not in parts[4]
+            )
+            if is_script:
+                try:
+                    _record_digest(digest)
+                    if not size.isdecimal():
+                        raise ValueError
+                except ValueError:
+                    raise _runtime_closure_refused(
+                        "a generated runtime script row is invalid"
+                    ) from None
+                continue
+            if pure.is_absolute() or any(part in {"", ".", ".."} for part in parts):
+                raise _runtime_closure_refused("a required runtime RECORD path is unsafe")
+            installer_owned = (
+                len(parts) >= 2
+                and str(pure.parent) == dist_info
+                and pure.name in _INSTALLER_OWNED_RECORD_MEMBERS
+            )
+            if pure.name == "RECORD" and str(pure.parent) == dist_info:
+                if digest or size:
+                    raise _runtime_closure_refused("the installed RECORD self-row is invalid")
+                continue
+            try:
+                expected_digest = _record_digest(digest)
+                if not size.isdecimal():
+                    raise ValueError
+                expected_size = int(size)
+            except ValueError:
+                raise _runtime_closure_refused(
+                    "a required runtime RECORD digest or size is invalid"
+                ) from None
+            if installer_owned:
+                continue
+            total_bytes += expected_size
+            if total_bytes > _MAX_RUNTIME_CLOSURE_BYTES:
+                raise _runtime_closure_refused("the runtime closure exceeds its byte limit")
+            observed_digest, fingerprint, _captured = _read_runtime_member(
+                root_fd, tuple(parts), expected_size
+            )
+            if observed_digest != expected_digest:
+                raise _runtime_closure_refused("a runtime member differs from its installed RECORD")
+            rows.append({"path": path, "sha256": digest, "size": size})
+            fingerprints.append((path, *fingerprint))
+    finally:
+        os.close(root_fd)
+    if not rows:
+        raise _runtime_closure_refused("a required runtime distribution has no wheel-owned members")
+    rows.sort(key=lambda item: item["path"])
+    fingerprints.sort(key=lambda item: item[0])
+    return hashlib.sha256(canonical_json_bytes(rows)).hexdigest(), tuple(fingerprints)
+
+
+def _portable_record_sha256(distribution: Any, record: str) -> str:
+    digest, _fingerprints = _portable_record_binding(distribution, record)
+    return digest
+
+
+def _snapshot_runtime(
+    distributions: dict[str, Any],
+    root: Path | None = None,
+) -> tuple[Path, dict[str, _SnapshotDistribution]]:
+    """Copy authenticated runtime members into one private import root."""
+
+    root = Path(tempfile.mkdtemp(prefix="mostlyright-neural-runtime-")) if root is None else root
+    snapshots: dict[str, _SnapshotDistribution] = {}
+    try:
+        for name, distribution in distributions.items():
+            record = distribution.read_text("RECORD")
+            if record is None:
+                raise _runtime_closure_refused(f"required runtime distribution {name} lost RECORD")
+            _portable_record_binding(distribution, record)
+            source_root = Path(distribution.locate_file(""))
+            source_fd = os.open(
+                source_root,
+                os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+            )
+            try:
+                for path, digest, size in csv.reader(io.StringIO(record, newline="")):
+                    pure = PurePosixPath(path)
+                    parts = pure.parts
+                    if (
+                        not path
+                        or pure.is_absolute()
+                        or any(part in {"", ".", ".."} for part in parts)
+                    ):
+                        continue
+                    if ".dist-info/" in path and pure.name in _INSTALLER_OWNED_RECORD_MEMBERS:
+                        continue
+                    if not digest or not size:
+                        continue
+                    expected_size = int(size)
+                    expected_digest = _record_digest(digest)
+                    observed, _state, payload = _read_runtime_member(
+                        source_fd, tuple(parts), expected_size, capture=True
+                    )
+                    if observed != expected_digest or payload is None:
+                        raise _runtime_closure_refused(
+                            "a runtime member changed while its private snapshot was created"
+                        )
+                    destination = root.joinpath(*parts)
+                    destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+                    descriptor = os.open(
+                        destination,
+                        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0),
+                        0o500 if destination.suffix in {".so", ".dylib", ".dll", ".pyd"} else 0o400,
+                    )
+                    try:
+                        view = memoryview(payload)
+                        while view:
+                            written = os.write(descriptor, view)
+                            view = view[written:]
+                    finally:
+                        os.close(descriptor)
+            finally:
+                os.close(source_fd)
+            snapshots[name] = _SnapshotDistribution(distribution, root, record)
+        return root, snapshots
+    except BaseException:
+        shutil.rmtree(root, ignore_errors=True)
+        raise
+
+
+def _installed_runtime_closure_sha256() -> str:
+    return hashlib.sha256(canonical_json_bytes(_installed_runtime_closure())).hexdigest()
+
+
+def _runtime_installation_state(
+    distributions: dict[str, Any],
+) -> tuple[tuple[str, str, tuple[tuple[str, int, int, int, int], ...]], ...]:
+    state = []
+    for name, distribution in sorted(distributions.items()):
+        record = distribution.read_text("RECORD")
+        if record is None:
+            raise _runtime_closure_refused(
+                f"required runtime distribution {name} has no installed RECORD"
+            )
+        digest, fingerprints = _portable_record_binding(distribution, record)
+        state.append((name, digest, fingerprints))
+    return tuple(state)
+
+
+def _require_runtime_closure(expected_sha256: str) -> dict[str, Any]:
+    closure, distributions = _installed_runtime_closure_with_distributions()
+    observed_sha256 = hashlib.sha256(canonical_json_bytes(closure)).hexdigest()
+    if not _is_sha256(expected_sha256) or observed_sha256 != expected_sha256:
+        raise SourceContractError(
+            "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+            "embedding.runtime",
+            "the installed neural dependency closure differs from the tuple PIN",
+        )
+    return distributions
+
+
+def _within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+_STDLIB_SEARCH = tuple(
+    value
+    for value in sys.path
+    if isinstance(value, str)
+    and value
+    and any(_within(Path(value).resolve(), root) for root in _STDLIB_ROOTS)
+    and not any(_within(Path(value).resolve(), root) for root in _THIRD_PARTY_ROOTS)
+)
+
+
+class _AuthenticatedRuntimeLoader:
+    def __init__(self, delegate: Any, verify: Any, origin: str) -> None:
+        self._delegate = delegate
+        self._verify = verify
+        self._origin = origin
+
+    def create_module(self, spec: Any) -> Any:
+        self._verify()
+        create = getattr(self._delegate, "create_module", None)
+        return None if create is None else create(spec)
+
+    def exec_module(self, module: Any) -> None:
+        payload = self._verify()
+        if self._origin.endswith(".py"):
+            if not isinstance(payload, bytes):
+                raise ImportError("authenticated runtime source bytes are unavailable")
+            code = compile(payload, self._origin, "exec", dont_inherit=True)
+            exec(code, module.__dict__)
+        else:
+            self._delegate.exec_module(module)
+        self._verify()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._delegate, name)
+
+
+class _AuthenticatedRuntimeFinder:
+    """Resolve runtime packages and standard-library imports from closed roots."""
+
+    def __init__(self, distributions: dict[str, Any]) -> None:
+        self._owners: dict[str, tuple[Path, frozenset[str], dict[str, tuple[bytes, int]], Any]] = {}
+        for _distribution_name, distribution in distributions.items():
+            root = Path(distribution.locate_file("")).resolve(strict=True)
+            record = distribution.read_text("RECORD")
+            if record is None:
+                raise _runtime_closure_refused("an authenticated runtime distribution lost RECORD")
+            members = frozenset(
+                PurePosixPath(str(item)).as_posix()
+                for item in distribution.files or ()
+                if not str(item).startswith("../")
+            )
+            expected: dict[str, tuple[bytes, int]] = {}
+            try:
+                for path, digest, size in csv.reader(io.StringIO(record, newline="")):
+                    if path in members and digest and size:
+                        expected[path] = (_record_digest(digest), int(size))
+            except (ValueError, csv.Error):
+                raise _runtime_closure_refused(
+                    "an authenticated runtime distribution has an invalid RECORD"
+                ) from None
+            for member in members:
+                first = PurePosixPath(member).parts[0]
+                if ".dist-info" in first or ".data" in first:
+                    continue
+                top_level = first.split(".", 1)[0]
+                if not top_level.isidentifier():
+                    continue
+                existing = self._owners.get(top_level)
+                if existing is not None and existing[3] is not distribution:
+                    raise _runtime_closure_refused(
+                        f"runtime package {top_level} is owned by more than one distribution"
+                    )
+                self._owners[top_level] = (root, members, expected, distribution)
+        self._stdlib_roots = _STDLIB_ROOTS
+        self._third_party_roots = _THIRD_PARTY_ROOTS
+        self._stdlib_search = _STDLIB_SEARCH
+
+    def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> Any:
+        del target
+        top_level = fullname.partition(".")[0]
+        owner = self._owners.get(top_level)
+        if owner is not None:
+            root, members, expected, _distribution = owner
+            spec = PathFinder.find_spec(fullname, [str(root)] if path is None else path)
+            self._validate_runtime_spec(fullname, spec, root, members)
+            if spec.loader is not None:
+                spec.loader = _AuthenticatedRuntimeLoader(
+                    spec.loader,
+                    lambda: self._verify_runtime_origin(fullname, spec, root, expected),
+                    spec.origin,
+                )
+            return spec
+        search = self._stdlib_search if path is None else path
+        spec = PathFinder.find_spec(fullname, search)
+        self._validate_stdlib_spec(fullname, spec)
+        return spec
+
+    def _validate_runtime_spec(
+        self, fullname: str, spec: Any, root: Path, members: frozenset[str]
+    ) -> None:
+        if spec is None or (spec.loader is None and spec.submodule_search_locations is None):
+            raise ImportError(f"authenticated runtime module {fullname} is unavailable")
+        if isinstance(spec.origin, str):
+            try:
+                relative = Path(spec.origin).resolve(strict=True).relative_to(root).as_posix()
+            except (OSError, RuntimeError, ValueError):
+                raise ImportError(
+                    f"runtime module {fullname} is outside its authenticated root"
+                ) from None
+            if relative not in members:
+                raise ImportError(f"runtime module {fullname} is absent from its wheel RECORD")
+            return
+        locations = spec.submodule_search_locations
+        if locations is None:
+            raise ImportError(f"runtime namespace {fullname} has no authenticated location")
+        prefix = fullname.replace(".", "/") + "/"
+        if not any(member.startswith(prefix) for member in members):
+            raise ImportError(f"runtime namespace {fullname} is absent from its wheel RECORD")
+        if any(not _within(Path(location).resolve(strict=True), root) for location in locations):
+            raise ImportError(f"runtime namespace {fullname} is outside its authenticated root")
+
+    def _verify_runtime_origin(
+        self,
+        fullname: str,
+        spec: Any,
+        root: Path,
+        expected: dict[str, tuple[bytes, int]],
+    ) -> bytes | None:
+        if not isinstance(spec.origin, str):
+            return None
+        try:
+            relative = Path(spec.origin).resolve(strict=True).relative_to(root).as_posix()
+            digest, size = expected[relative]
+            root_fd = os.open(
+                root,
+                os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+            )
+            try:
+                observed, _fingerprint, payload = _read_runtime_member(
+                    root_fd,
+                    tuple(PurePosixPath(relative).parts),
+                    size,
+                    capture=spec.origin.endswith(".py"),
+                )
+            finally:
+                os.close(root_fd)
+        except (KeyError, OSError, RuntimeError, SourceContractError, ValueError):
+            raise ImportError(f"runtime module {fullname} changed before execution") from None
+        if observed != digest:
+            raise ImportError(f"runtime module {fullname} changed before execution")
+        return payload
+
+    def _validate_stdlib_spec(self, fullname: str, spec: Any) -> None:
+        if spec is None:
+            raise ImportError(f"undeclared runtime dependency {fullname} is unavailable")
+        if spec.origin in {"built-in", "frozen"}:
+            return
+        if isinstance(spec.origin, str):
+            try:
+                origin = Path(spec.origin).resolve(strict=True)
+            except (OSError, RuntimeError):
+                raise ImportError(
+                    f"standard-library module {fullname} has an invalid origin"
+                ) from None
+            if any(_within(origin, root) for root in self._third_party_roots):
+                raise ImportError(f"undeclared runtime dependency {fullname} is not authenticated")
+            if any(_within(origin, root) for root in self._stdlib_roots):
+                return
+        raise ImportError(f"undeclared runtime dependency {fullname} is outside closed roots")
+
+
+class _RuntimeImportGuard:
+    def __init__(self, distributions: dict[str, Any]) -> None:
+        self.finder = _AuthenticatedRuntimeFinder(distributions)
+        self._meta_path: list[Any] = []
+        self._removed: dict[str, Any] = {}
+
+    def __enter__(self) -> None:
+        self._meta_path = list(sys.meta_path)
+        for name, module in tuple(sys.modules.items()):
+            if module is None:
+                continue
+            spec = getattr(module, "__spec__", None)
+            origin = getattr(spec, "origin", None)
+            if origin in {"built-in", "frozen"}:
+                continue
+            if isinstance(origin, str):
+                try:
+                    resolved = Path(origin).resolve(strict=True)
+                except (OSError, RuntimeError):
+                    resolved = None
+                if (
+                    resolved is not None
+                    and any(_within(resolved, root) for root in self.finder._stdlib_roots)
+                    and not any(_within(resolved, root) for root in self.finder._third_party_roots)
+                ):
+                    continue
+            removed = sys.modules.pop(name, None)
+            if removed is not None:
+                self._removed[name] = removed
+        sys.meta_path[:] = [BuiltinImporter, FrozenImporter, self.finder]
+
+    def __exit__(self, _type: Any, _value: Any, _traceback: Any) -> None:
+        sys.meta_path[:] = self._meta_path
+        owned = set(self.finder._owners)
+        for name in tuple(sys.modules):
+            if name.partition(".")[0] in owned:
+                sys.modules.pop(name, None)
+        for name, module in self._removed.items():
+            sys.modules.setdefault(name, module)
+
+
+def _runtime_module_spec(distribution: Any, module_name: str) -> Any:
+    """Resolve a top-level package only beneath the distribution whose bytes were authenticated."""
+
+    try:
+        root = Path(distribution.locate_file("")).resolve(strict=True)
+        expected_relative = f"{module_name}/__init__.py"
+        members = distribution.files
+        if members is None or expected_relative not in {
+            PurePosixPath(str(item)).as_posix() for item in members
+        }:
+            raise ValueError
+        unresolved = root / expected_relative
+        opened = os.lstat(unresolved)
+        if not stat.S_ISREG(opened.st_mode):
+            raise ValueError
+        expected = unresolved.resolve(strict=True)
+        expected.relative_to(root)
+        spec = PathFinder.find_spec(module_name, [str(root)])
+        if spec is None or spec.loader is None or not isinstance(spec.origin, str):
+            raise ValueError
+        if Path(spec.origin).resolve(strict=True) != expected:
+            raise ValueError
+        return spec
+    except (OSError, RuntimeError, ValueError):
+        raise SourceContractError(
+            "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+            "embedding.runtime",
+            f"the authenticated {module_name} module could not be resolved",
+        ) from None
+
+
+def _require_runtime_module_origin(module: Any, distribution: Any, module_name: str) -> None:
+    """Require an imported runtime package to come from its authenticated distribution."""
+
+    try:
+        root = Path(distribution.locate_file("")).resolve(strict=True)
+        raw_origin = getattr(module, "__file__", None)
+        if not isinstance(raw_origin, str) or not raw_origin:
+            raise ValueError
+        origin = Path(raw_origin)
+        opened = os.lstat(origin)
+        if not stat.S_ISREG(opened.st_mode):
+            raise ValueError
+        resolved = origin.resolve(strict=True)
+        relative = resolved.relative_to(root).as_posix()
+        members = distribution.files
+        if members is None or relative not in {
+            PurePosixPath(str(item)).as_posix() for item in members
+        }:
+            raise ValueError
+    except (metadata.PackageNotFoundError, OSError, RuntimeError, ValueError):
+        raise SourceContractError(
+            "NEURAL_RUNTIME_CLOSURE_MISMATCH",
+            "embedding.runtime",
+            f"the imported {module_name} module is outside its authenticated distribution",
+        ) from None
+
+
+def _load_authenticated_runtime_module(
+    distribution: Any, module_name: str, finder: _AuthenticatedRuntimeFinder | None = None
+) -> Any:
+    """Load a runtime package from its authenticated origin without consulting import hooks."""
+
+    spec = (
+        _runtime_module_spec(distribution, module_name)
+        if finder is None
+        else finder.find_spec(module_name)
+    )
+    existing = sys.modules.get(module_name)
+    if existing is not None:
+        _require_runtime_module_origin(existing, distribution, module_name)
+        return existing
+    module = module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except (ImportError, ModuleNotFoundError):
+        sys.modules.pop(module_name, None)
+        raise SourceContractError(
+            "NEURAL_RUNTIME_UNAVAILABLE",
+            "embedding.runtime",
+            "the exact optional neural runtime could not be imported",
+        ) from None
+    except BaseException:
+        sys.modules.pop(module_name, None)
+        raise
+    _require_runtime_module_origin(module, distribution, module_name)
+    return module
+
+
+def _load_runtime(
+    model_bytes: bytes,
+    tokenizer_bytes: bytes,
+    expected_closure_sha256: str,
+    snapshot_root: Path | None = None,
+) -> tuple[Any, Any, Any, _RuntimeImportGuard, Path]:
+    installed = _require_runtime_closure(expected_closure_sha256)
+    snapshot_root, distributions = _snapshot_runtime(installed, snapshot_root)
+    snapshot_closure = {
+        "distributions": sorted(
+            (
+                {
+                    "name": name,
+                    "record_sha256": _portable_record_sha256(
+                        distribution, distribution.read_text("RECORD") or ""
+                    ),
+                    "version": distribution.version,
+                }
+                for name, distribution in distributions.items()
+            ),
+            key=lambda item: item["name"],
+        ),
+        "roots": list(_RUNTIME_ROOT_DISTRIBUTIONS),
+        "schema_version": "local-search-neural-installed-closure.v2",
+    }
+    if hashlib.sha256(canonical_json_bytes(snapshot_closure)).hexdigest() != (
+        expected_closure_sha256
+    ):
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+        raise _runtime_closure_refused("the private runtime snapshot differs from the tuple PIN")
+    before = _runtime_installation_state(distributions)
+    for distribution_name, expected in RUNTIME_VERSIONS.items():
+        distribution = distributions[canonicalize_name(distribution_name)]
+        observed = distribution.version
+        if observed != expected:
+            raise SourceContractError(
+                "NEURAL_RUNTIME_MISMATCH",
+                "embedding.runtime",
+                f"{distribution_name} must be exactly {expected}, observed {observed}",
+            )
+    guard = _RuntimeImportGuard(distributions)
+    try:
+        guard.__enter__()
+        np = _load_authenticated_runtime_module(distributions["numpy"], "numpy", guard.finder)
+        ort = _load_authenticated_runtime_module(
+            distributions["onnxruntime"], "onnxruntime", guard.finder
+        )
+        tokenizers = _load_authenticated_runtime_module(
+            distributions["tokenizers"], "tokenizers", guard.finder
+        )
+
+        options = ort.SessionOptions()
+        options.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL
+        options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_BASIC
+        options.inter_op_num_threads = 1
+        options.intra_op_num_threads = 1
+        options.enable_mem_pattern = False
+        options.enable_cpu_mem_arena = False
+        options.use_deterministic_compute = True
+        options.add_session_config_entry("session.inter_op.allow_spinning", "0")
+        options.add_session_config_entry("session.intra_op.allow_spinning", "0")
+        try:
+            session = ort.InferenceSession(
+                model_bytes,
+                sess_options=options,
+                providers=["CPUExecutionProvider"],
+            )
+            session.disable_fallback()
+            if session.get_providers() != ["CPUExecutionProvider"]:
+                raise SourceContractError(
+                    "NEURAL_PROVIDER",
+                    "embedding.runtime",
+                    "the runtime enabled an undeclared execution provider",
+                )
+            tokenizer = tokenizers.Tokenizer.from_str(tokenizer_bytes.decode("utf-8"))
+        except SourceContractError:
+            raise
+        except Exception:
+            raise SourceContractError(
+                "NEURAL_SESSION_UNAVAILABLE",
+                "embedding.runtime",
+                "the verified sidecar could not create the pinned local session",
+            ) from None
+        tokenizer.enable_truncation(MAX_LENGTH, direction="right", strategy="longest_first")
+        pad_id = tokenizer.token_to_id("[PAD]")
+        if pad_id is None:
+            raise SourceContractError(
+                "NEURAL_TOKENIZER",
+                "embedding.runtime",
+                "the pinned tokenizer has no padding token",
+            )
+        tokenizer.enable_padding(
+            direction="right", pad_id=pad_id, pad_token="[PAD]", length=MAX_LENGTH
+        )
+        after = _runtime_installation_state(distributions)
+    except BaseException:
+        guard.__exit__(*sys.exc_info())
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+        raise
+    before_roots = {
+        name: Path(distribution.locate_file("")).resolve(strict=True)
+        for name, distribution in distributions.items()
+    }
+    after_roots = {
+        name: Path(distribution.locate_file("")).resolve(strict=True)
+        for name, distribution in distributions.items()
+    }
+    if before != after or before_roots != after_roots:
+        guard.__exit__(None, None, None)
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+        raise _runtime_closure_refused("the runtime installation changed while it was loaded")
+    return np, session, tokenizer, guard, snapshot_root
+
+
+def _encode_with_runtime(runtime: tuple[Any, ...], text: str) -> tuple[int, ...]:
+    np, session, tokenizer = runtime[:3]
+    encoded = tokenizer.encode(text, add_special_tokens=True)
+    input_names = {item.name for item in session.get_inputs()}
+    arrays = {
+        "input_ids": np.asarray([encoded.ids], dtype=np.int64),
+        "attention_mask": np.asarray([encoded.attention_mask], dtype=np.int64),
+        "token_type_ids": np.asarray([encoded.type_ids], dtype=np.int64),
+    }
+    feed = {name: arrays[name] for name in input_names if name in arrays}
+    if set(feed) != input_names:
+        raise SourceContractError(
+            "NEURAL_MODEL_INPUT",
+            "embedding.model",
+            "the pinned model declares an unsupported input set",
+        )
+    outputs = session.run(None, feed)
+    if len(outputs) != 1 or outputs[0].ndim != 3:
+        raise SourceContractError(
+            "NEURAL_MODEL_OUTPUT",
+            "embedding.model",
+            "the pinned model did not emit one token-embedding tensor",
+        )
+    hidden = outputs[0].astype(np.float32, copy=False)
+    if hidden.shape[0] != 1 or hidden.shape[2] != DIMENSIONS:
+        raise SourceContractError(
+            "NEURAL_MODEL_OUTPUT",
+            "embedding.model",
+            "the pinned model emitted the wrong batch or embedding dimension",
+        )
+    mask = arrays["attention_mask"].astype(np.float32)[..., None]
+    pooled = (hidden * mask).sum(axis=1, dtype=np.float32) / mask.sum(axis=1, dtype=np.float32)
+    norm = np.sqrt((pooled * pooled).sum(axis=1, dtype=np.float32), dtype=np.float32)[..., None]
+    if bool(np.any(norm == 0)):
+        raise SourceContractError(
+            "NEURAL_ZERO_VECTOR",
+            "embedding.model",
+            "the pinned model emitted a zero-norm vector",
+        )
+    normalized = pooled / norm
+    magnitude = np.floor(np.abs(normalized) * VECTOR_SCALE + np.float32(0.5)).astype(np.int64)
+    quantized = np.where(normalized < 0, -magnitude, magnitude)
+    if bool(np.any(quantized < _INT32_MIN)) or bool(np.any(quantized > _INT32_MAX)):
+        raise SourceContractError(
+            "NEURAL_VECTOR_RANGE",
+            "embedding.vector",
+            "quantized output exceeded signed int32",
+        )
+    return tuple(int(value) for value in quantized[0])
+
+
+def _runtime_worker(
+    connection: Any,
+    model_bytes: bytes,
+    tokenizer_bytes: bytes,
+    expected_closure_sha256: str,
+    snapshot_root: Path,
+) -> None:
+    runtime: tuple[Any, ...] | None = None
+    try:
+        runtime = _load_runtime(
+            model_bytes, tokenizer_bytes, expected_closure_sha256, snapshot_root
+        )
+        connection.send({"status": "ready"})
+        while True:
+            command, value = connection.recv()
+            if command == "close":
+                return
+            if command != "encode" or not isinstance(value, str):
+                raise SourceContractError(
+                    "NEURAL_SESSION_UNAVAILABLE",
+                    "embedding.runtime",
+                    "the bounded neural worker received an invalid request",
+                )
+            vector = _encode_with_runtime(runtime, value)
+            connection.send({"peak_rss_bytes": _peak_rss_bytes(), "status": "ok", "vector": vector})
+    except SourceContractError as error:
+        connection.send(
+            {"code": error.code, "detail": error.detail, "path": error.path, "status": "error"}
+        )
+    except (EOFError, BrokenPipeError, OSError):
+        return
+    except Exception:
+        try:
+            connection.send(
+                {
+                    "code": "NEURAL_SESSION_UNAVAILABLE",
+                    "detail": "the bounded neural worker failed",
+                    "path": "embedding.runtime",
+                    "status": "error",
+                }
+            )
+        except (BrokenPipeError, EOFError, OSError):
+            pass
+    finally:
+        if runtime is not None:
+            runtime[3].__exit__(None, None, None)
+            shutil.rmtree(runtime[4], ignore_errors=True)
+        connection.close()
+
+
+def _start_worker(
+    model_bytes: bytes, tokenizer_bytes: bytes, expected_closure_sha256: str
+) -> tuple[Any, Any, Path]:
+    _require_runtime_closure(expected_closure_sha256)
+    snapshot_root = Path(tempfile.mkdtemp(prefix="mostlyright-neural-runtime-"))
+    context = multiprocessing.get_context("spawn")
+    parent, child = context.Pipe(duplex=True)
+    process = context.Process(
+        target=_runtime_worker,
+        args=(child, model_bytes, tokenizer_bytes, expected_closure_sha256, snapshot_root),
+        daemon=True,
+        name="mostlyright-local-neural",
+    )
+    try:
+        process.start()
+    except Exception:
+        parent.close()
+        child.close()
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+        raise SourceContractError(
+            "NEURAL_SESSION_UNAVAILABLE",
+            "embedding.runtime",
+            "the bounded neural worker could not start",
+        ) from None
+    child.close()
+    try:
+        response = _receive_worker_result(
+            parent,
+            process,
+            timeout_seconds=MAX_RUNTIME_INITIALIZATION_SECONDS,
+            snapshot_root=snapshot_root,
+            timeout_detail=(
+                "runtime initialization exceeded the pinned wall-time limit and its worker was "
+                "terminated"
+            ),
+        )
+    except SourceContractError:
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+        raise
+    if response.get("status") == "error":
+        _terminate_worker(parent, process, snapshot_root)
+        raise SourceContractError(
+            response.get("code", "NEURAL_SESSION_UNAVAILABLE"),
+            response.get("path", "embedding.runtime"),
+            response.get("detail", "the bounded neural worker failed during initialization"),
+        )
+    if response != {"status": "ready"}:
+        _terminate_worker(parent, process, snapshot_root)
+        raise SourceContractError(
+            "NEURAL_SESSION_UNAVAILABLE",
+            "embedding.runtime",
+            "the bounded neural worker returned an invalid initialization response",
+        )
+    return parent, process, snapshot_root
+
+
+def _terminate_worker(connection: Any, process: Any, snapshot_root: Path | None = None) -> None:
+    if process.is_alive():
+        try:
+            connection.send(("close", None))
+        except (BrokenPipeError, EOFError, OSError):
+            pass
+        process.join(_WORKER_JOIN_SECONDS)
+    try:
+        connection.close()
+    except OSError:
+        pass
+    if process.is_alive():
+        process.terminate()
+    process.join(_WORKER_JOIN_SECONDS)
+    if process.is_alive():
+        process.kill()
+        process.join(_WORKER_JOIN_SECONDS)
+    if snapshot_root is not None:
+        shutil.rmtree(snapshot_root, ignore_errors=True)
+
+
+def _receive_worker_result(
+    connection: Any,
+    process: Any,
+    *,
+    timeout_seconds: float,
+    snapshot_root: Path | None = None,
+    timeout_detail: str = (
+        "encoding exceeded the pinned wall-time limit and its worker was terminated"
+    ),
+) -> dict[str, Any]:
+    try:
+        ready = connection.poll(timeout_seconds)
+    except OSError:
+        _terminate_worker(connection, process, snapshot_root)
+        raise SourceContractError(
+            "NEURAL_SESSION_UNAVAILABLE",
+            "embedding.runtime",
+            "the bounded neural worker exited without a result",
+        ) from None
+    if not ready:
+        _terminate_worker(connection, process, snapshot_root)
+        raise SourceContractError(
+            "NEURAL_TIME_LIMIT",
+            "embedding.runtime",
+            timeout_detail,
+        )
+    try:
+        response = connection.recv()
+    except (EOFError, OSError):
+        _terminate_worker(connection, process, snapshot_root)
+        raise SourceContractError(
+            "NEURAL_SESSION_UNAVAILABLE",
+            "embedding.runtime",
+            "the bounded neural worker exited without a result",
+        ) from None
+    if not isinstance(response, dict):
+        _terminate_worker(connection, process, snapshot_root)
+        raise SourceContractError(
+            "NEURAL_SESSION_UNAVAILABLE",
+            "embedding.runtime",
+            "the bounded neural worker returned an invalid result",
+        )
+    return response
+
+
+def _peak_rss_bytes() -> int:
+    peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return peak if sys.platform == "darwin" else peak * 1024