sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/model_adapters.py

@@ -0,0 +1,438 @@
+"""Lazy, CPU-only model scorers. No third-party package is imported at discovery.
+
+A caller supplies an existing pinned snapshot and its complete file digest.
+Preflight never resolves a remote model name. Scores are raw ranking utilities,
+not calibrated relevance probabilities. Local inference timings exclude load.
+"""
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import importlib.util
+import math
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+
+from .contracts import ContractError, canonical_json
+from .integration_contracts import CandidateConfiguration, require_digest, value_digest
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    model_id: str
+    checkpoint: str
+    revision: str
+    max_length: int
+    batch_size: int
+    backend: str = "cross_encoder"
+    trust_remote_code: bool = False
+    onnx_file: str | None = None
+
+    def to_dict(self):
+        return dict(vars(self))
+
+
+MODEL_SPECS = MappingProxyType({spec.model_id: spec for spec in (
+    ModelSpec("minilm-l6-v2", "cross-encoder/ms-marco-MiniLM-L-6-v2", "233902d25c440f23af6f7d6e94d2946bac0bee0a", 512, 16),
+    ModelSpec("jina-turbo-v1", "jinaai/jina-reranker-v1-turbo-en", "b8c14f4e723d9e0aab4732a7b7b93741eeeb77c2", 192, 16, trust_remote_code=True),
+    ModelSpec("gte-modernbert-base", "Alibaba-NLP/gte-reranker-modernbert-base", "f7481e6055501a30fb19d090657df9ec1f79ab2c", 512, 8, trust_remote_code=True),
+    ModelSpec("gte-modernbert-int8", "Alibaba-NLP/gte-reranker-modernbert-base", "f7481e6055501a30fb19d090657df9ec1f79ab2c", 512, 16, backend="onnx_int8", onnx_file="onnx/model_int8.onnx"),
+    ModelSpec("mxbai-xsmall-v1", "mixedbread-ai/mxbai-rerank-xsmall-v1", "b5c6e9da73abc3711f593f705371cdbe9e0fe422", 512, 16),
+)})
+MODEL_IMPLEMENTATION_DIGEST = "sha256:" + hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
+
+
+class ModelUnavailableError(ContractError):
+    """A required local snapshot, runtime or backend is unavailable."""
+
+
+def get_model_spec(model_id: str) -> ModelSpec:
+    try:
+        return MODEL_SPECS[model_id]
+    except (KeyError, TypeError) as exc:
+        raise ContractError("unsupported model ID; inspect MODEL_SPECS") from exc
+
+
+def _file_digest(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            h.update(block)
+    return "sha256:" + h.hexdigest()
+
+
+def _directory_alias(path: Path) -> bool:
+    """Recognize directory links without following them, including NT junctions."""
+    info = path.lstat()
+    attributes = getattr(info, "st_file_attributes", 0)
+    # Windows directory reparse points include junctions and other directory
+    # aliases; file blob symlinks deliberately retain their content-bound policy.
+    return (path.is_symlink() and path.is_dir()) or bool(attributes & 0x400 and attributes & 0x10)
+
+
+def _snapshot_root(snapshot_path: str | Path) -> Path:
+    path = Path(snapshot_path).expanduser().absolute()
+    if not path.is_dir():
+        raise ModelUnavailableError("pinned local snapshot directory missing")
+    if _directory_alias(path):
+        raise ModelUnavailableError("snapshot directory symlinks/reparse aliases are unsupported")
+    return path.resolve()
+
+
+def snapshot_identity(snapshot_path: str | Path) -> dict:
+    """Bind every relative filename and file contents, including HF blob links.
+
+    Inspect each directory before descending: rglob can conceal linked trees on
+    some platforms. No directory symlink, junction or directory reparse alias is
+    allowed, even when it contains no referenced Python module.
+    """
+    path = _snapshot_root(snapshot_path)
+    files, directories = {}, [path]
+    while directories:
+        for item in sorted(directories.pop().iterdir()):
+            if _directory_alias(item):
+                raise ModelUnavailableError("snapshot directory symlinks/reparse aliases are unsupported")
+            if item.is_dir():
+                directories.append(item)
+            elif item.is_file():
+                files[item.relative_to(path).as_posix()] = _file_digest(item)
+            else:
+                raise ModelUnavailableError("snapshot contains a missing file target or unsupported file")
+    if not files:
+        raise ModelUnavailableError("pinned local snapshot is empty")
+    return {"snapshot_files": files, "snapshot_digest": value_digest(files)}
+
+
+def _validate_custom_code(path: Path) -> None:
+    """Resolve static model/tokenizer imports using one local package policy.
+
+    This is a conservative syntax-based closure check, not a Python sandbox or
+    proof of arbitrary program behavior. Local packages require __init__.py;
+    wildcard imports, known dynamic loaders and undeclared external imports
+    are unavailable. Known loader/execution helper modules are excluded as a
+    whole at import/reference boundaries, so renamed imports cannot evade the
+    policy. Direct loader primitives and package hooks are also excluded.
+    Remaining stdlib and declared backend package roots are external.
+    This finite policy does not detect every way Python can construct or execute
+    code. Source is parsed, never imported or executed.
+    """
+    pending, visited, trees = [], set(), {}
+    external = sys.stdlib_module_names | {"torch", "transformers", "sentence_transformers", "onnxruntime", "numpy"}
+    # Whole-module exclusions deliberately include benign members: accepting a
+    # loader module under an alias would require proving all later uses safe.
+    # pkgutil/pydoc wrap imports, importlib/imp expose loader machinery,
+    # runpy executes modules, and builtins exposes import/compile/eval/exec.
+    loader_modules = {"pkgutil", "pydoc", "importlib", "runpy", "builtins", "imp"}
+    loader_primitives = {
+        "__import__", "compile", "eval", "exec", "import_module", "resolve_name",
+        "locate", "safeimport", "run_module", "run_path", "load_module",
+        "load_source", "load_compiled", "load_dynamic", "exec_module",
+        "get_importer", "find_loader", "iter_importers",
+        "module_from_spec", "spec_from_loader", "spec_from_file_location",
+        "SourceFileLoader", "SourcelessFileLoader", "ExtensionFileLoader",
+        "LazyLoader",
+    }
+    package_hooks = {"__getattr__", "__path__"}
+    unsupported_references = loader_modules | loader_primitives | package_hooks
+
+    def parse(source):
+        if source not in trees:
+            relative = source.relative_to(path).as_posix()
+            try:
+                trees[source] = ast.parse(source.read_text(encoding="utf-8"), filename=relative)
+            except (SyntaxError, UnicodeError) as exc:
+                raise ModelUnavailableError("pinned local custom-code cannot be parsed: " + relative) from exc
+        return trees[source]
+
+    def resolve(parts, *, required=True):
+        """Queue package parents and return the unique local module/package."""
+        if not parts or any(not part.isidentifier() for part in parts):
+            raise ModelUnavailableError("unsafe or outside pinned local custom-code path")
+        for depth in range(1, len(parts) + 1):
+            base = path.joinpath(*parts[:depth])
+            module, initializer = base.with_suffix(".py"), base / "__init__.py"
+            if module.is_file() and initializer.is_file():
+                raise ModelUnavailableError("ambiguous pinned local custom-code module/package: " + ".".join(parts[:depth]))
+            if depth < len(parts):
+                if not initializer.is_file():
+                    if required:
+                        raise ModelUnavailableError("pinned local custom-code module missing: " + ".".join(parts))
+                    return None
+                pending.append(initializer)
+            elif initializer.is_file():
+                pending.append(initializer)
+                return initializer
+            elif module.is_file():
+                pending.append(module)
+                return module
+            elif base.is_dir():
+                raise ModelUnavailableError("local namespace package lacks a provable initializer: " + ".".join(parts))
+        if required:
+            raise ModelUnavailableError("pinned local custom-code module missing: " + ".".join(parts))
+        return None
+
+    def local(parts, *, relative=False):
+        root = path / parts[0]
+        if relative or root.exists() or root.with_suffix(".py").exists():
+            return resolve(parts)
+        if parts[0] not in external:
+            raise ModelUnavailableError("undeclared external or missing local custom-code module: " + ".".join(parts))
+        return None
+
+    def binds(source, name):
+        # A package may export a class/function/value rather than a child module.
+        # Existing child code always takes precedence for closure traversal.
+        for node in parse(source).body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and node.name == name:
+                return True
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                if any((alias.asname or (alias.name.split(".")[0] if isinstance(node, ast.Import) else alias.name)) == name for alias in node.names):
+                    return True
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target] if isinstance(node, ast.AnnAssign) else []
+            if any(isinstance(target, ast.Name) and target.id == name for target in targets):
+                return True
+        return False
+
+    def children(parts, source, names):
+        if source is not None and source.name != "__init__.py":
+            return  # from a_module import an_attribute does not load a child.
+        for alias in names:
+            child = resolve(parts + [alias.name], required=False)
+            if child is None and (source is None or not binds(source, alias.name)):
+                raise ModelUnavailableError("pinned local custom-code module missing: " + ".".join(parts + [alias.name]))
+
+    root_init = path / "__init__.py"
+    for filename in ("config.json", "tokenizer_config.json"):
+        try:
+            config = json.loads((path / filename).read_text(encoding="utf-8"))
+            auto_map = config.get("auto_map", {})
+            if not isinstance(auto_map, dict):
+                raise TypeError("auto_map")
+        except (ValueError, TypeError, AttributeError, UnicodeError) as exc:
+            raise ContractError("invalid pinned custom-code configuration: " + filename) from exc
+        for references in auto_map.values():
+            for reference in references if isinstance(references, list) else [references]:
+                if reference is None:
+                    continue
+                if not isinstance(reference, str) or "--" in reference:
+                    raise ModelUnavailableError("custom-code reference requires another repository; complete pinned local code closure required")
+                module, separator, class_name = reference.rpartition(".")
+                if not separator or not class_name.isidentifier():
+                    raise ModelUnavailableError("unsafe pinned local custom-code reference")
+                resolve(module.split("."))
+                if root_init.is_file():
+                    pending.append(root_init)
+
+    while pending:
+        source = pending.pop()
+        if source in visited:
+            continue
+        visited.add(source)
+        package = list(source.relative_to(path).parts[:-1])
+        for node in ast.walk(parse(source)):
+            # Reject direct references even when stored for a later call.
+            # Import exclusions below use original module/symbol names, before
+            # aliasing, and apply to every parsed transitive local source.
+            if ((isinstance(node, ast.Name) and node.id in unsupported_references)
+                    or (isinstance(node, ast.Attribute) and node.attr in unsupported_references)
+                    or (isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name in unsupported_references)):
+                raise ModelUnavailableError("dynamic custom-code loading is unsupported; static local closure required")
+            if not isinstance(node, (ast.Import, ast.ImportFrom)):
+                continue
+            names = [alias.name for alias in node.names] if isinstance(node, ast.Import) else [node.module or ""]
+            if (any(name.split(".")[0] in loader_modules for name in names)
+                    or any(alias.name.rsplit(".", 1)[-1] in loader_primitives | package_hooks for alias in node.names)):
+                raise ModelUnavailableError("dynamic custom-code loading is unsupported; static local closure required")
+            if any(alias.name == "*" for alias in node.names):
+                raise ModelUnavailableError("custom-code wildcard lacks a provable module closure")
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    local(alias.name.split("."))
+                continue
+            if node.level:
+                if node.level - 1 > len(package):
+                    raise ModelUnavailableError("relative custom-code import escapes pinned snapshot")
+                parent = package[:len(package) - (node.level - 1)]
+                parts = parent + (node.module.split(".") if node.module else [])
+                dependency = resolve(parts) if parts else root_init if root_init.is_file() else None
+                if dependency is not None:
+                    pending.append(dependency)
+            else:
+                parts = node.module.split(".")
+                dependency = local(parts)
+                if dependency is None:
+                    continue
+            children(parts, dependency, node.names)
+
+
+def preflight_model(model_id: str, snapshot_path: str | Path, expected_snapshot_digest: str | None = None, *, check_backend: bool = True) -> dict:
+    """Check snapshot completeness and optional runtime without loading models."""
+    spec = get_model_spec(model_id)
+    path = _snapshot_root(snapshot_path)
+    if path.name != spec.revision:
+        raise ModelUnavailableError("snapshot directory must name the exact pinned model revision")
+    if not path.is_dir() or not (path / "config.json").is_file():
+        raise ModelUnavailableError("complete pinned local snapshot required: config.json missing")
+    if not (path / "tokenizer_config.json").is_file() or not any((path / name).is_file() for name in ("tokenizer.json", "vocab.txt", "vocab.json", "spiece.model", "sentencepiece.bpe.model")):
+        raise ModelUnavailableError("complete pinned tokenizer files required")
+    identity = snapshot_identity(path)
+    _validate_custom_code(path)
+    if spec.backend == "onnx_int8":
+        if not (path / spec.onnx_file).is_file():
+            raise ModelUnavailableError("pinned official INT8 ONNX graph missing")
+    else:
+        weights = list(path.glob("*.safetensors")) + list(path.glob("pytorch_model*.bin"))
+        if not weights:
+            raise ModelUnavailableError("pinned model weights missing")
+        # Reject partial sharded snapshots before the optional loader is invoked.
+        import json
+        for index in path.glob("*.index.json"):
+            try:
+                shards = set(json.loads(index.read_text(encoding="utf-8"))["weight_map"].values())
+            except (ValueError, KeyError, TypeError) as exc:
+                raise ContractError("invalid model weight index") from exc
+            if any(not isinstance(name, str) or Path(name).is_absolute() or ".." in Path(name).parts or not (path / name).is_file() for name in shards):
+                raise ModelUnavailableError("pinned sharded weights incomplete")
+    if expected_snapshot_digest is not None:
+        require_digest(expected_snapshot_digest, "model_snapshot_digest")
+        if identity["snapshot_digest"] != expected_snapshot_digest:
+            raise ContractError("pinned model snapshot digest differs")
+    if check_backend:
+        if sys.version_info[:2] != (3, 12):
+            raise ModelUnavailableError("optional model execution requires Python 3.12; backend compatibility is unverified")
+        packages = ("onnxruntime", "numpy", "transformers") if spec.backend == "onnx_int8" else ("torch", "sentence_transformers", "transformers")
+        missing = [name for name in packages if importlib.util.find_spec(name) is None]
+        if missing:
+            raise ModelUnavailableError("optional backend packages missing: " + ", ".join(missing))
+    return {**spec.to_dict(), **identity, "device": "cpu", "activation": "identity", "truncation": "longest_first", "tokenizer_revision": spec.revision}
+
+
+def _scores(values, count: int) -> tuple[float, ...]:
+    try:
+        result = tuple(float(value) for value in values)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ContractError("model output must contain scalar ranking utilities") from exc
+    if len(result) != count or any(not math.isfinite(value) for value in result):
+        raise ContractError("model score coverage differs or contains nonfinite values")
+    return result
+
+
+def request_pairs(request: Mapping) -> tuple[tuple[str, str], ...]:
+    if not isinstance(request, Mapping) or request.get("schema_version") != "sphynx.rag.rerank.request.v1":
+        raise ContractError("unsupported model rerank request")
+    query, candidates = request.get("query"), request.get("candidates")
+    if not isinstance(query, str) or not query.strip() or not isinstance(candidates, (tuple, list)) or not candidates:
+        raise ContractError("model request requires query and nonempty candidates")
+    ids, pairs = [], []
+    for item in candidates:
+        if not isinstance(item, Mapping) or not isinstance(item.get("candidate_id"), str) or not isinstance(item.get("input"), str) or not item["candidate_id"] or not item["input"].strip():
+            raise ContractError("model candidate requires ID and input text")
+        ids.append(item["candidate_id"])
+        pairs.append((query, item["input"]))
+    if len(set(ids)) != len(ids):
+        raise ContractError("duplicate model candidate IDs")
+    for name in ("case_id", "query_id", "pool_digest"):
+        if not isinstance(request.get(name), str) or not request[name]:
+            raise ContractError("model request identity missing")
+    return tuple(pairs)
+
+
+class OfflineModelScorer:
+    """Lazy frozen scorer; construction/configuration do not import ML packages.
+
+    ``score_pairs`` supports fusion/retrieval callers; ``__call__`` preserves the
+    existing rerank response protocol and ordered pool coverage. Full request,
+    dataset, pool and configuration identities belong in the caller's capture.
+    """
+    def __init__(self, model_id: str, snapshot_path: str | Path, expected_snapshot_digest: str, *, threads: int = 4):
+        self.spec = get_model_spec(model_id)
+        self.snapshot_path = Path(snapshot_path).expanduser().absolute()
+        require_digest(expected_snapshot_digest, "model_snapshot_digest")
+        if type(threads) is not int or not 1 <= threads <= 64:
+            raise ContractError("threads must be an integer between 1 and 64")
+        self.snapshot_digest, self.threads = expected_snapshot_digest, threads
+        self._model = self._tokenizer = self._torch = None
+        self._loaded_identity = None
+
+    @property
+    def configuration(self) -> CandidateConfiguration:
+        return CandidateConfiguration(self.spec.model_id + "-offline-v1", "sphynx.offline-model.v1", MODEL_IMPLEMENTATION_DIGEST,
+            {**self.spec.to_dict(), "device": "cpu", "threads": self.threads, "seed": 0, "activation": "identity", "truncation": "longest_first", "tokenizer_revision": self.spec.revision, "offline": True},
+            "trusted_local", self.spec.checkpoint, self.spec.revision, self.snapshot_digest)
+
+    def preflight(self) -> dict:
+        return preflight_model(self.spec.model_id, self.snapshot_path, self.snapshot_digest)
+
+    def _load(self):
+        self._loaded_identity = self.preflight()
+        # Force offline flags before importing packages. Never restore a permissive
+        # network setting while this scorer or another lazy adapter can execute.
+        os.environ["HF_HUB_OFFLINE"] = "1"
+        os.environ["TRANSFORMERS_OFFLINE"] = "1"
+        os.environ["TOKENIZERS_PARALLELISM"] = "false"
+        if self.spec.backend == "onnx_int8":
+            import onnxruntime as ort
+            from transformers import AutoTokenizer
+            self._tokenizer = AutoTokenizer.from_pretrained(str(self.snapshot_path), local_files_only=True, trust_remote_code=self.spec.trust_remote_code)
+            options = ort.SessionOptions()
+            options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+            options.intra_op_num_threads = self.threads
+            self._model = ort.InferenceSession(str(self.snapshot_path / self.spec.onnx_file), sess_options=options, providers=["CPUExecutionProvider"])
+        else:
+            import inspect
+            import torch
+            from sentence_transformers import CrossEncoder
+            self._torch = torch
+            torch.set_num_threads(self.threads)
+            torch.manual_seed(0)
+            kwargs = {"model_name_or_path": str(self.snapshot_path), "device": "cpu", "max_length": self.spec.max_length, "trust_remote_code": self.spec.trust_remote_code}
+            accepted = inspect.signature(CrossEncoder).parameters
+            if "local_files_only" in accepted:
+                kwargs["local_files_only"] = True
+            elif "model_kwargs" in accepted and "tokenizer_kwargs" in accepted:
+                kwargs["model_kwargs"] = {"local_files_only": True}
+                kwargs["tokenizer_kwargs"] = {"local_files_only": True}
+            else:
+                raise ModelUnavailableError("CrossEncoder backend lacks enforceable local_files_only support")
+            if "trust_remote_code" not in accepted and self.spec.trust_remote_code:
+                raise ModelUnavailableError("CrossEncoder backend lacks pinned local custom-code support")
+            self._model = CrossEncoder(**kwargs)
+
+    def score_pairs(self, pairs: Sequence[tuple[str, str]]) -> tuple[float, ...]:
+        pairs = tuple(pairs)
+        if not pairs or any(not isinstance(pair, (tuple, list)) or len(pair) != 2 or any(not isinstance(text, str) or not text.strip() for text in pair) for pair in pairs):
+            raise ContractError("score_pairs requires nonempty query/document text pairs")
+        if self._model is None:
+            self._load()
+        else:
+            # Recheck the file closure even when model weights are in memory.
+            # This keeps later captures from claiming a changed local snapshot.
+            preflight_model(self.spec.model_id, self.snapshot_path, self.snapshot_digest, check_backend=False)
+        if self.spec.backend == "cross_encoder":
+            values = self._model.predict(list(pairs), batch_size=self.spec.batch_size, show_progress_bar=False, convert_to_numpy=True, activation_fn=self._torch.nn.Identity())
+            return _scores(values.reshape(-1).tolist(), len(pairs))
+        import numpy as np
+        values = []
+        input_names = {item.name for item in self._model.get_inputs()}
+        for start in range(0, len(pairs), self.spec.batch_size):
+            batch = pairs[start:start + self.spec.batch_size]
+            encoded = self._tokenizer([p[0] for p in batch], [p[1] for p in batch], padding=True, truncation="longest_first", max_length=self.spec.max_length, return_tensors="np")
+            if not input_names <= set(encoded):
+                raise ModelUnavailableError("tokenizer does not supply all frozen ONNX inputs")
+            feed = {name: np.asarray(encoded[name], dtype=np.int64) for name in input_names}
+            values.extend(np.asarray(self._model.run(None, feed)[0], dtype=float).reshape(-1).tolist())
+        return _scores(values, len(pairs))
+
+    def __call__(self, request: Mapping) -> dict:
+        values = self.score_pairs(request_pairs(request))
+        return {"schema_version": "sphynx.rag.rerank.response.v1", "query_id": request["query_id"], "pool_digest": request["pool_digest"], "scores": [{"candidate_id": item["candidate_id"], "ranking_score": value} for item, value in zip(request["candidates"], values)]}
+
+
+def create_model_scorer(model_id: str, snapshot_path: str | Path, expected_snapshot_digest: str, *, threads: int = 4) -> OfflineModelScorer:
+    return OfflineModelScorer(model_id, snapshot_path, expected_snapshot_digest, threads=threads)
+

sphynx/model_catalog_data.py

@@ -0,0 +1,30 @@
+"""Content-free optional model capability records; no cache or ML imports."""
+from .catalog import CandidateDescriptor
+from .integration_contracts import ScoreField
+
+_LOCAL_SOURCE = 'sha256:619729f450a24430bbe2c1641a6fe47723cc9f616385ec7814f3fcb52e2249c1'
+_RECORDED_SOURCE = 'sha256:352086665411a7f44429ccd73b9f778d001f5ed727a09ea560cb740a9533f437'
+_FIELDS = (ScoreField("ranking_score", "utility", "higher", "model_score"),)
+_MODELS = ("minilm-l6-v2", "jina-turbo-v1", "gte-modernbert-base", "gte-modernbert-int8", "mxbai-xsmall-v1")
+CANDIDATES = tuple(CandidateDescriptor(
+    candidate_id="model-" + model_id + "-offline-v1", track="rerank",
+    interface_version="sphynx.offline-model.v1", source_digest=_LOCAL_SOURCE,
+    supported_dataset_ids=(), execution_modes=("trusted_local",),
+    implementation_status="available",
+    reason="Offline implementation available; runtime support unverified. Matching optional ML packages and complete pinned snapshots require caller preflight; fresh backend smoke for every profile remains unverified.",
+    local_prerequisites=("complete revision-named local snapshot and SHA-256 file closure", "matching pinned tokenizer/config/weights", "Python 3.12 required intended runtime; optional backend compatibility unverified"),
+    dependencies=("onnxruntime", "numpy", "transformers") if model_id == "gte-modernbert-int8" else ("torch", "sentence-transformers", "transformers"),
+    score_fields=_FIELDS, model_identity_required=True, supported_python=(),
+) for model_id in _MODELS) + tuple(CandidateDescriptor(
+    candidate_id="model-" + model_id + "-recorded-v2", track="rerank",
+    interface_version="sphynx.recorded.rerank.v2", source_digest=_RECORDED_SOURCE,
+    supported_dataset_ids=(), execution_modes=("recorded",), implementation_status="available",
+    local_prerequisites=("exact complete dataset-bound score artifact and SHA-256", "dataset/cohort/reference/policy identity", "pinned original pools for expanded source import"),
+    score_fields=_FIELDS, supported_python=("3.11", "3.12", "3.13", "3.14"),
+) for model_id in _MODELS) + tuple(CandidateDescriptor(
+    candidate_id="model-" + model_id + "-prescreen", track="rerank",
+    interface_version="sphynx.model-prescreen.v1", source_digest=None,
+    supported_dataset_ids=(), execution_modes=("recorded",), implementation_status="blocked",
+    reason="Historical prescreen has only partial query coverage; no complete validated confirmation recording or supported lazy adapter. Experimental/incomplete.",
+    local_prerequisites=("separately approved complete recording and implementation",), score_fields=_FIELDS,
+) for model_id in ("qwen3-reranker-0.6b", "mxbai-base-v2", "bge-v2-m3"))