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

sphynx/hosted/benchmark_intake.py

@@ -0,0 +1,218 @@
+"""Trusted, offline SciFact development intake; never executes candidate code.
+
+Only the pinned existing public-only bundle and native BEIR SciFact files are
+accepted. Published sparse qrels are not converted into human negative labels.
+Exporting data does not register a hosted benchmark or prove redistribution rights.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+from types import MappingProxyType
+
+from ..benchmarks import AssetRef, BenchmarkCase, BenchmarkRegistry, BenchmarkRelease, LabelCase, LabelSetRelease
+from ..contracts import canonical_json
+from ..public_bundle import load_public_rerank_bundle
+from ..public_rerank import build_public_rerank_request, load_public_rerank_pack
+from .contracts import HostedError
+
+BENCHMARK_REF = "beir.scifact.bm25-top15.dev15@1.0.0"
+LABEL_REF = "beir.scifact.native-qrels.dev15@1.0.0"
+INPUT_REF = "beir.scifact.inputs.dev15@1.0.0"
+REFERENCE_REF = "beir.scifact.references.dev15@1.0.0"
+CORPUS_REF = "beir.scifact.pool-corpus.dev15@1.0.0"
+EVALUATION_ID = "rag.rerank.public.v1"
+METRIC_RELEASE = "rag.rerank.beir.metric.v1"
+GRADER_RELEASE = "rag.rerank.scifact.dev15.grader.v1"
+POLICY_REVISION = "native-sparse-qrels.unjudged-as-zero.pool-conditional.v1"
+VERSION = "1.0.0"
+INPUT_SCHEMA = "sphynx.hosted.public-rerank.inputs.v1"
+REFERENCE_SCHEMA = "sphynx.hosted.public-rerank.references.v1"
+METADATA_SCHEMA = "sphynx.hosted.public-benchmark.v1"
+BUNDLE_SCHEMA = "sphynx.hosted.public-benchmark-bundle.v1"
+FILES = ("inputs.json", "references.json", "benchmark.json")
+REGISTERED_LOCATORS = MappingProxyType({INPUT_REF: "inputs.json", REFERENCE_REF: "references.json", BENCHMARK_REF: "benchmark.json"})
+# Operator-owned byte pins. They are not supplied by a candidate or inferred from
+# its freshly edited manifest. Tests substitute only fictional public fixtures.
+SOURCE_PINS = MappingProxyType({
+    "manifest.json": "739df50af296cd5760c5499e8711005f7bba35ad30e2aaa08d667fa19c45465d",
+    "frozen-pools.json": "b3e6a31c62eccd90962bbce6372efe9bbf9fd397beedea7ea01d3a777e7d28f6",
+    "corpus.jsonl": "dec31c8182f3d744c7d2c09423756fd1d17cbef75808db13ba01cc0aab4d1ac6",
+    "queries.jsonl": "8ff84a7c903f722981cd8d595c022660140c51867b27608a6d4910db86080313",
+    "qrels/test.tsv": "0864bb985e0ca2367ba217977e72004d549054b2b06666ed9d4825ac7c21284c",
+})
+MAX_FILE_BYTES = 16 * 1024 * 1024
+
+
+def _require(condition, code="invalid_public_benchmark"):
+    if not condition:
+        raise HostedError(code, "public benchmark inputs or provenance are invalid")
+
+
+def encoded(value):
+    return (canonical_json(value) + "\n").encode("utf-8")
+
+
+def byte_digest(raw):
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def read_json(raw):
+    _require(type(raw) is bytes and 0 < len(raw) <= MAX_FILE_BYTES)
+    def unique(pairs):
+        result = {}
+        for key, item in pairs:
+            _require(key not in result, "duplicate_public_field")
+            result[key] = item
+        return result
+    try:
+        return json.loads(raw, object_pairs_hook=unique,
+                          parse_constant=lambda _: (_ for _ in ()).throw(ValueError()))
+    except (ValueError, UnicodeError, RecursionError):
+        raise HostedError("invalid_public_benchmark", "public benchmark JSON is invalid") from None
+
+
+def _pinned(root, relative, digest):
+    root = Path(root).absolute()
+    _require(root.is_dir() and not root.is_symlink())
+    path = root.joinpath(*relative.split("/"))
+    _require(path.is_file() and not path.is_symlink() and path.resolve().is_relative_to(root.resolve()))
+    _require(path.stat().st_size <= MAX_FILE_BYTES)
+    raw = path.read_bytes()
+    _require(byte_digest(raw) == "sha256:" + digest, "public_source_digest_mismatch")
+    return raw
+
+
+def corpus_projection(requests, references):
+    documents = {}
+    for request, reference in zip(requests, references):
+        for candidate, label in zip(request["candidates"], reference["pool"]):
+            doc = label["document_id"]
+            _require(doc not in documents or documents[doc] == candidate["input"])
+            documents[doc] = candidate["input"]
+    return {"schema_version": "sphynx.public-rerank.pool-corpus.v1", "documents": [
+        {"document_id": key, "input": value} for key, value in sorted(documents.items())]}
+
+
+def build_release_records(inputs, references, corpus):
+    input_asset = AssetRef(INPUT_REF, VERSION, byte_digest(encoded(inputs)))
+    ref_asset = AssetRef(REFERENCE_REF, VERSION, byte_digest(encoded(references)))
+    corpus_asset = AssetRef(CORPUS_REF, VERSION, byte_digest(encoded(corpus)))
+    cases = tuple(BenchmarkCase(request["case_id"], byte_digest(encoded(request)), "scifact", "development",
+        "unclassified", "unclassified", None, len(request["query"].split())) for request in inputs["requests"])
+    labels = LabelSetRelease("sphynx.label-set-release.v1", LABEL_REF, VERSION, input_asset, corpus_asset,
+        ref_asset, "passage_qrels", POLICY_REVISION, METRIC_RELEASE, "native_public_qrels",
+        "native_qrels_unjudged", tuple(LabelCase(case.case_id, case.input_digest, "judged") for case in cases), (), ())
+    benchmark = BenchmarkRelease("sphynx.benchmark-release.v1", BENCHMARK_REF, VERSION, EVALUATION_ID,
+        GRADER_RELEASE, "sphynx.rag.rerank.v1", "component", input_asset, corpus_asset, labels.asset_ref,
+        "passage_qrels", METRIC_RELEASE, "any", "development", cases)
+    BenchmarkRegistry((labels,), (benchmark,)).resolve(BENCHMARK_REF)
+    return labels, benchmark
+
+
+@dataclass(frozen=True)
+class PublicBenchmarkExport:
+    directory: Path
+    manifest_sha256: str
+    benchmark_ref: str
+    benchmark_digest: str
+    label_digest: str
+
+
+def export_scifact_development(public_bundle_dir, native_scifact_dir, output_dir):
+    """Validate fixed public sources, then create a new four-file data package.
+
+    Candidate execution receives only inputs.json. Full sparse native judgments
+    for the selected queries and pool judgment-presence flags stay grader-only.
+    No network, cloud operations, model imports or execution occur.
+    """
+    source_raw = _pinned(public_bundle_dir, "frozen-pools.json", SOURCE_PINS["frozen-pools.json"])
+    _pinned(public_bundle_dir, "manifest.json", SOURCE_PINS["manifest.json"])
+    bundle = load_public_rerank_bundle(public_bundle_dir, expected_manifest_sha256=SOURCE_PINS["manifest.json"])
+    _require(bundle.dataset_sha256 == SOURCE_PINS["frozen-pools.json"])
+    native_raw = {name: _pinned(native_scifact_dir, name, SOURCE_PINS[name]) for name in
+                  ("corpus.jsonl", "queries.jsonl", "qrels/test.tsv")}
+    def jsonl(raw):
+        return [read_json(line) for line in raw.splitlines() if line.strip()]
+    corpus, queries = {}, {}
+    for row in jsonl(native_raw["corpus.jsonl"]):
+        _require(type(row) is dict and type(row.get("_id")) is str and row["_id"] not in corpus)
+        _require(type(row.get("title")) is str and type(row.get("text")) is str)
+        corpus[row["_id"]] = (row["title"] + " " + row["text"]).strip()
+    for row in jsonl(native_raw["queries.jsonl"]):
+        _require(type(row) is dict and type(row.get("_id")) is str and row["_id"] not in queries and type(row.get("text")) is str)
+        queries[row["_id"]] = row["text"]
+    try:
+        lines = native_raw["qrels/test.tsv"].decode("utf-8").splitlines()
+        _require(lines[0] == "query-id\tcorpus-id\tscore")
+        qrels = {}
+        for line in lines[1:]:
+            query, doc, score = line.split("\t")
+            _require(query in queries and doc in corpus and score in ("0", "1", "2", "3"))
+            _require(doc not in qrels.setdefault(query, {}))
+            qrels[query][doc] = int(score)
+    except (ValueError, IndexError, UnicodeError):
+        raise HostedError("invalid_public_benchmark", "native qrels are invalid") from None
+    _require((len(corpus), len(queries), len(qrels), sum(map(len, qrels.values()))) == (5183, 1109, 300, 339))
+    pack = load_public_rerank_pack(bundle.dataset_path, split="development", expected_sha256=bundle.dataset_sha256)
+    selected = [row for row in pack.rows if row["dataset"] == "scifact"]
+    _require(len(selected) == 15)
+    requests, refs = [], []
+    for row in selected:
+        query_id = row["query_id"]
+        _require(query_id in qrels and row["query"] == queries.get(query_id) and any(v > 0 for v in qrels[query_id].values()))
+        labels = []
+        for candidate in row["candidates"]:
+            doc = candidate["document_id"]
+            _require(candidate["input"] == corpus.get(doc) and candidate["candidate_id"] == "scifact:" + doc)
+            native = qrels[query_id].get(doc)
+            _require(candidate["grade"] == (native if native is not None else 0), "native_qrel_alignment_mismatch")
+            labels.append({"candidate_id": candidate["candidate_id"], "document_id": doc,
+                           "native_judged": native is not None, "native_grade": native})
+        requests.append(build_public_rerank_request(pack, row["task_id"]))
+        refs.append({"case_id": row["task_id"], "query_id": query_id,
+                     "qrels": dict(sorted(qrels[query_id].items())), "pool": labels})
+    _require(sum(any(c["native_grade"] is not None and c["native_grade"] > 0 for c in row["pool"]) for row in refs) == 14)
+    _require(sum(c["native_judged"] for row in refs for c in row["pool"]) == 14)
+    inputs = {"schema_version": INPUT_SCHEMA, "benchmark_ref": BENCHMARK_REF, "requests": requests}
+    references = {"schema_version": REFERENCE_SCHEMA, "benchmark_ref": BENCHMARK_REF,
+                  "policy_revision": POLICY_REVISION, "queries": refs}
+    projected_corpus = corpus_projection(requests, refs)
+    label_release, benchmark_release = build_release_records(inputs, references, projected_corpus)
+    metadata = {"schema_version": METADATA_SCHEMA, "benchmark_release": benchmark_release.to_dict(),
+        "label_release": label_release.to_dict(), "corpus_projection_schema": projected_corpus["schema_version"],
+        "registered_asset_locators": dict(REGISTERED_LOCATORS),
+        "provenance": {"source_files": {name: "sha256:" + value for name, value in sorted(SOURCE_PINS.items())},
+            "original_archive_url": "https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/scifact.zip",
+            "original_archive_sha256": "sha256:536e14446a0ba56ed1398ab1055f39fe852686ecad24a6306c80c490fa8e0165",
+            "native_qrel_source": "qrels/test.tsv", "native_provenance_verified": True,
+            "review_receipts_verified": False, "human_review_claimed": False,
+            "selection": "existing_scifact_development_15_bm25_top15", "previously_opened": True,
+            "fresh_holdout": False, "use": "development_regression",
+            "licenses": [
+                {"asset": "claims_and_evidence", "license": "CC-BY-4.0", "source": "https://github.com/allenai/scifact/blob/master/LICENSE.md"},
+                {"asset": "abstracts", "license": "ODC-BY-1.0", "source": "https://github.com/allenai/scifact/blob/master/LICENSE.md"},
+                {"asset": "beir_repackaging_declared", "license": "CC-BY-SA-4.0", "source": "https://huggingface.co/datasets/BeIR/scifact"}],
+            "changes": ["select previously opened 15 development queries", "retain BM25 top15 order and scores",
+                        "preserve absent native qrels as null with explicit effective-zero metric policy"],
+            "distribution_rights_inferred": False},
+        "population": {"case_count": 15, "pool_passages": 225, "native_judged_passages": 14,
+            "unjudged_passages": 211, "quality_eligible_cases": 14, "pool_miss_cases": 1},
+        "metric_policy": {"top_k": 5, "relevance_threshold": 1, "gain": "2**native_grade-1",
+            "unjudged_passage_effective_grade": 0, "unjudged_passages_are_human_negatives": False,
+            "quality_population": "queries_with_positive_native_qrel_in_frozen_pool",
+            "empty_positive_pool": "undefined", "failed_eligible_response": "missing",
+            "latency": "trusted_runner_process_wall_including_startup_and_model_loading"}}
+    contents = {"inputs.json": encoded(inputs), "references.json": encoded(references), "benchmark.json": encoded(metadata)}
+    manifest = {"schema_version": BUNDLE_SCHEMA, "benchmark_ref": BENCHMARK_REF,
+        "benchmark_digest": benchmark_release.digest, "label_digest": label_release.digest,
+        "files": {name: {"digest": byte_digest(raw), "size_bytes": len(raw)} for name, raw in contents.items()}}
+    root = Path(output_dir).absolute()
+    _require(not root.exists() and not root.is_symlink(), "public_export_exists")
+    root.mkdir(parents=True, exist_ok=False)
+    for name, raw in {**contents, "manifest.json": encoded(manifest)}.items():
+        with root.joinpath(name).open("xb") as stream:
+            stream.write(raw)
+    return PublicBenchmarkExport(root, byte_digest(encoded(manifest)), BENCHMARK_REF, benchmark_release.digest, label_release.digest)

sphynx/hosted/contracts.py

@@ -0,0 +1,361 @@
+"""Strict, versioned configuration for the first hosted reranking pilot.
+
+Parsing never installs dependencies, downloads weights, or executes candidate code.
+Version 1 retains the standard-library CPU profile. A single version 2 model
+configuration requires separate operator admission before source publication.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import tomllib
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from ..contracts import INTERFACE_VERSION, CandidateSpec, ContractError, canonical_json
+
+CONFIG_SCHEMA = "sphynx.candidate.repository.v1"
+FAMILY_SCHEMA = "sphynx.candidate.family.v1"
+FAMILY_SELECTION_SCHEMA = "sphynx.candidate.family-selection.v1"
+FAMILY_SUBMISSION_SCHEMA = "sphynx.hosted.prepared-submission.v2"
+MAX_FAMILY_METHODS = 8
+RUNTIME_PROFILE = "python-cpu.v1"
+MAX_CONFIG_BYTES = 65_536
+MAX_FILE_BYTES = 262_144
+MAX_SOURCE_BYTES = 1_048_576
+MAX_SOURCE_FILES = 16
+_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
+
+
+class HostedError(ValueError):
+    """A payload-free diagnostic with a stable error code."""
+
+    def __init__(self, code: str, message: str):
+        self.code = code
+        super().__init__(f"{code}: {message}")
+
+
+def fields(value: object, expected: set[str], label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or set(value) != expected:
+        raise HostedError("invalid_configuration", f"{label} has missing or unsupported fields")
+    return value
+
+
+def stable_id(value: object, label: str) -> str:
+    if not isinstance(value, str) or not _ID.fullmatch(value):
+        raise HostedError("invalid_configuration", f"{label} must be a stable identifier")
+    return value
+
+
+def source_path(value: object) -> str:
+    if not isinstance(value, str) or not value or len(value) > 240:
+        raise HostedError("invalid_source_path", "source paths must be short relative paths")
+    parts = value.split("/")
+    if any(part in ("", ".", "..") or part.startswith(".") for part in parts):
+        raise HostedError("invalid_source_path", "source paths cannot contain hidden or traversal components")
+    if not re.fullmatch(r"[A-Za-z0-9_./-]+", value):
+        raise HostedError("invalid_source_path", "source paths must use portable relative names")
+    return value
+
+
+def argv(value: object, label: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not 1 <= len(value) <= 32:
+        raise HostedError("invalid_configuration", f"{label} must be an argv array")
+    if any(not isinstance(arg, str) or not arg.strip() or "\x00" in arg or len(arg) > 1024 for arg in value):
+        raise HostedError("invalid_configuration", f"{label} contains invalid arguments")
+    if value[0] != "python":
+        raise HostedError("unsupported_runtime", f"{label} must use the platform Python interpreter")
+    return tuple(value)
+
+
+@dataclass(frozen=True)
+class CandidateConfig:
+    name: str
+    version: str
+    interface_version: str
+    entry_point: tuple[str, ...]
+    source_files: tuple[str, ...]
+    execution_kind: str
+    build_commands: tuple[tuple[str, ...], ...]
+    dependencies: tuple[str, ...]
+    runtime_profile: str
+    python: str
+    model_kind: str
+    method_json: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "schema_version": CONFIG_SCHEMA,
+            "candidate": {
+                "name": self.name, "version": self.version,
+                "interface_version": self.interface_version,
+                "entry_point": list(self.entry_point), "source_files": list(self.source_files),
+                "execution_kind": self.execution_kind,
+            },
+            "build": {"commands": [list(command) for command in self.build_commands],
+                      "dependencies": list(self.dependencies)},
+            "runtime": {"profile": self.runtime_profile, "python": self.python},
+            "model": {"kind": self.model_kind},
+        }
+        if self.method_json is not None:
+            result["method"] = json.loads(self.method_json)
+        return result
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + hashlib.sha256(canonical_json(self.to_dict()).encode("utf-8")).hexdigest()
+
+    def candidate_spec(self) -> CandidateSpec:
+        return CandidateSpec(self.name, self.version, self.entry_point, self.interface_version)
+
+
+def _load_configuration(payload: bytes) -> Mapping[str, Any]:
+    if not isinstance(payload, bytes) or not 0 < len(payload) <= MAX_CONFIG_BYTES:
+        raise HostedError("invalid_configuration", "configuration must be bounded UTF-8 TOML")
+    try:
+        raw = tomllib.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError, RecursionError):
+        raise HostedError("invalid_configuration", "configuration is not valid UTF-8 TOML") from None
+    return raw
+
+
+def parse_candidate_config(payload: bytes) -> CandidateConfig:
+    """Parse a single configuration; model parsing does not grant admission."""
+    raw = _load_configuration(payload)
+    if raw.get("schema_version") == "sphynx.candidate.repository.v2":
+        return _parse_registered_model(raw)
+    return _parse_candidate_config(raw)
+
+
+def _parse_registered_model(raw):
+    try:
+        from .model_contracts import parse_model_configuration
+    except ModuleNotFoundError as exc:
+        if exc.name != __package__ + ".model_contracts":
+            raise
+        raise HostedError("models_not_admitted", "this platform payload does not admit model candidates") from None
+    return parse_model_configuration(raw)
+
+
+def _parse_candidate_config(raw: Mapping[str, Any]) -> CandidateConfig:
+    if not isinstance(raw, Mapping):
+        raise HostedError("invalid_configuration", "candidate configuration must be a table")
+    fields(raw, {"schema_version", "candidate", "build", "runtime", "model"} |
+           ({"method"} if "method" in raw else set()), "configuration")
+    if raw["schema_version"] != CONFIG_SCHEMA:
+        raise HostedError("unsupported_configuration_version", "expected " + CONFIG_SCHEMA)
+    candidate = fields(raw["candidate"], {
+        "name", "version", "interface_version", "entry_point", "source_files", "execution_kind",
+    }, "candidate")
+    build = fields(raw["build"], {"commands", "dependencies"}, "build")
+    runtime = fields(raw["runtime"], {"profile", "python"}, "runtime")
+    model = fields(raw["model"], {"kind"}, "model")
+    name = stable_id(candidate["name"], "candidate.name")
+    version = stable_id(candidate["version"], "candidate.version")
+    if candidate["interface_version"] != INTERFACE_VERSION:
+        raise HostedError("unsupported_interface", "expected " + INTERFACE_VERSION)
+    command = argv(candidate["entry_point"], "candidate.entry_point")
+    if len(command) < 2 or not command[1].endswith(".py"):
+        raise HostedError("invalid_entry_point", "entry point must be python followed by a declared .py file")
+    entry_file = source_path(command[1])
+    sources = candidate["source_files"]
+    if not isinstance(sources, list) or not 1 <= len(sources) <= MAX_SOURCE_FILES:
+        raise HostedError("invalid_configuration", "source_files must declare 1 to 16 Python files")
+    sources = tuple(source_path(path) for path in sources)
+    if any(not path.endswith(".py") for path in sources) or len({path.casefold() for path in sources}) != len(sources):
+        raise HostedError("invalid_configuration", "source_files must contain unique portable .py paths")
+    if entry_file not in sources:
+        raise HostedError("invalid_entry_point", "entry point must appear in source_files")
+    if candidate["execution_kind"] != "reranker":
+        raise HostedError("unsupported_execution_kind", "the first pilot supports fresh reranker execution only")
+    commands = build["commands"]
+    if not isinstance(commands, list) or len(commands) > 8:
+        raise HostedError("invalid_configuration", "build.commands must contain at most eight argv arrays")
+    commands = tuple(argv(command, "build.commands") for command in commands)
+    if not isinstance(build["dependencies"], list):
+        raise HostedError("invalid_configuration", "build.dependencies must be an array")
+    if build["dependencies"]:
+        raise HostedError("dependencies_not_supported", "this pilot requires dependencies = []; an offline dependency broker is pending")
+    if runtime["profile"] != RUNTIME_PROFILE or runtime["python"] != "3.12":
+        raise HostedError("unsupported_runtime", "this pilot requires python-cpu.v1 with Python 3.12")
+    if model["kind"] != "none":
+        raise HostedError("models_not_supported", "this pilot requires model.kind = none; pinned model artifacts are pending")
+    method_json = None
+    if "method" in raw:
+        method = fields(raw["method"], {"description", "parameters", "random_seeds", "determinism"}, "method")
+        if not isinstance(method["description"], str) or not 1 <= len(method["description"]) <= 2048:
+            raise HostedError("invalid_configuration", "method.description must contain 1 to 2048 characters")
+        if method["determinism"] not in ("deterministic", "stochastic", "unspecified"):
+            raise HostedError("invalid_configuration", "method.determinism must be deterministic, stochastic, or unspecified")
+        if (not isinstance(method["random_seeds"], list) or len(method["random_seeds"]) > 16 or
+            any(type(seed) is not int or not 0 <= seed < 2**64 for seed in method["random_seeds"])):
+            raise HostedError("invalid_configuration", "method.random_seeds must contain at most 16 nonnegative integer seeds")
+        def validate_parameter(value, depth=0):
+            if depth > 5: raise HostedError("invalid_configuration", "method parameters are too deeply nested")
+            if isinstance(value, dict):
+                if len(value) > 32 or any(not isinstance(key, str) or not 1 <= len(key) <= 128 for key in value):
+                    raise HostedError("invalid_configuration", "method parameter keys are invalid")
+                for item in value.values(): validate_parameter(item, depth + 1)
+            elif isinstance(value, list):
+                if len(value) > 64: raise HostedError("invalid_configuration", "method parameter array is too long")
+                for item in value: validate_parameter(item, depth + 1)
+            elif not (type(value) in (bool, int) or isinstance(value, str) and len(value) <= 2048 or
+                      type(value) is float and math.isfinite(value)):
+                raise HostedError("invalid_configuration", "method parameters must be finite JSON values")
+        if not isinstance(method["parameters"], dict):
+            raise HostedError("invalid_configuration", "method.parameters must be a table")
+        validate_parameter(method["parameters"])
+        method_json = canonical_json(dict(method))
+    config = CandidateConfig(name, version, INTERFACE_VERSION, command, sources, "reranker",
+                             commands, (), RUNTIME_PROFILE, "3.12", "none", method_json)
+    try:
+        config.candidate_spec()
+    except ContractError:
+        raise HostedError("invalid_configuration", "candidate does not satisfy the existing CandidateSpec") from None
+    return config
+
+
+def candidate_method_id(value: object) -> str:
+    """Case-sensitive selector, never a path or an executable expression."""
+    if type(value) is not str or not 1 <= len(value) <= 128 or not _ID.fullmatch(value):
+        raise HostedError("invalid_candidate_method", "candidate_method must be a stable identifier of at most 128 characters")
+    return value
+
+
+@dataclass(frozen=True)
+class CandidateFamily:
+    name: str
+    version: str
+    default_method: str | None
+    methods: tuple[tuple[str, CandidateConfig], ...]
+
+    def __post_init__(self):
+        stable_id(self.name, "family.name"); stable_id(self.version, "family.version")
+        if len(self.name) > 128 or len(self.version) > 128:
+            raise HostedError("invalid_configuration", "family name and version must contain at most 128 characters")
+        if (type(self.methods) is not tuple or not 1 <= len(self.methods) <= MAX_FAMILY_METHODS
+                or any(type(item) is not tuple or len(item) != 2 or not isinstance(item[1], CandidateConfig) for item in self.methods)):
+            raise HostedError("invalid_configuration", "family methods must be a bounded immutable configuration list")
+        names = tuple(candidate_method_id(key) for key, _ in self.methods)
+        if len(set(names)) != len(names):
+            raise HostedError("invalid_configuration", "family method names must be unique")
+        if self.default_method is not None and candidate_method_id(self.default_method) not in names:
+            raise HostedError("candidate_method_not_found", "the declared family default is not one of its methods")
+
+    def to_dict(self) -> dict[str, Any]:
+        family = {"name": self.name, "version": self.version}
+        if self.default_method is not None:
+            family["default_method"] = self.default_method
+        return {"schema_version": FAMILY_SCHEMA, "family": family,
+                "methods": {key: config.to_dict() for key, config in self.methods}}
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + hashlib.sha256(canonical_json(self.to_dict()).encode()).hexdigest()
+
+    def select(self, candidate_method: str | None = None) -> tuple[str, CandidateConfig]:
+        key = candidate_method_id(candidate_method) if candidate_method is not None else self.default_method
+        if key is None:
+            raise HostedError("candidate_method_required", "this family has no default; specify one of its declared method names")
+        config = next((config for name, config in self.methods if name == key), None)
+        if config is None:
+            raise HostedError("candidate_method_not_found", "candidate_method is not declared in the pinned family manifest")
+        return key, config
+
+
+def _parse_candidate_family(raw: Mapping[str, Any]) -> CandidateFamily:
+    fields(raw, {"schema_version", "family", "methods"}, "candidate family")
+    if raw["schema_version"] != FAMILY_SCHEMA:
+        raise HostedError("unsupported_configuration_version", "expected " + FAMILY_SCHEMA)
+    family = fields(raw["family"], {"name", "version"} |
+                    ({"default_method"} if isinstance(raw["family"], Mapping) and "default_method" in raw["family"] else set()), "family")
+    name, version = stable_id(family["name"], "family.name"), stable_id(family["version"], "family.version")
+    methods = raw["methods"]
+    if not isinstance(methods, Mapping) or not 1 <= len(methods) <= MAX_FAMILY_METHODS:
+        raise HostedError("invalid_configuration", "a family must declare 1 to 8 named methods")
+    parsed = tuple((candidate_method_id(key), _parse_candidate_config(value)) for key, value in sorted(methods.items()))
+    default = candidate_method_id(family["default_method"]) if "default_method" in family else None
+    if default is not None and default not in methods:
+        raise HostedError("candidate_method_not_found", "the declared family default is not one of its methods")
+    return CandidateFamily(name, version, default, parsed)
+
+
+def parse_candidate_family(payload: bytes) -> CandidateFamily:
+    """Validate all declared configurations; never fetch or execute any method."""
+    return _parse_candidate_family(_load_configuration(payload))
+
+
+@dataclass(frozen=True)
+class SelectedCandidateRepository:
+    config: CandidateConfig
+    family: CandidateFamily | None = None
+    candidate_method: str | None = None
+    manifest_digest: str | None = None
+
+    def family_selection(self) -> dict[str, Any] | None:
+        if self.family is None:
+            return None
+        return {"schema_version": FAMILY_SELECTION_SCHEMA, "name": self.family.name,
+                "version": self.family.version, "method": self.candidate_method,
+                "manifest_digest": self.manifest_digest, "configuration_digest": self.family.digest}
+
+
+def parse_candidate_repository(payload: bytes, *, candidate_method: str | None = None) -> SelectedCandidateRepository:
+    if candidate_method is not None:
+        candidate_method = candidate_method_id(candidate_method)
+    raw = _load_configuration(payload)
+    if raw.get("schema_version") == FAMILY_SCHEMA:
+        family = _parse_candidate_family(raw)
+        key, config = family.select(candidate_method)
+        return SelectedCandidateRepository(config, family, key, "sha256:" + hashlib.sha256(payload).hexdigest())
+    if candidate_method is not None:
+        raise HostedError("candidate_method_not_supported", "single-candidate v1 repositories do not accept candidate_method")
+    if raw.get("schema_version") == "sphynx.candidate.repository.v2":
+        return SelectedCandidateRepository(_parse_registered_model(raw))
+    return SelectedCandidateRepository(_parse_candidate_config(raw))
+
+
+def verify_candidate_repository(payload: bytes, manifest: Mapping[str, Any]) -> SelectedCandidateRepository:
+    """Reparse frozen root bytes and bind the selected config and exact source closure.
+
+    Source byte/hash verification belongs to the caller; this verifies that the
+    frozen manifest can only build the configuration selected from those bytes.
+    """
+    if not isinstance(manifest, Mapping):
+        raise HostedError("candidate_selection_mismatch", "prepared candidate selection is invalid")
+    selection = parse_candidate_repository(payload, candidate_method=manifest.get("candidate_method"))
+    is_model = selection.config.model_kind == "registered"
+    if is_model:
+        from .model_contracts import MODEL_SUBMISSION_SCHEMA
+    if selection.family is None:
+        expected_schema = MODEL_SUBMISSION_SCHEMA if is_model else "sphynx.hosted.prepared-submission.v1"
+        if (manifest.get("schema_version") != expected_schema
+                or "candidate_method" in manifest or "candidate_family" in manifest):
+            raise HostedError("candidate_selection_mismatch", "single-candidate manifest contains a family selection")
+    elif (manifest.get("schema_version") != FAMILY_SUBMISSION_SCHEMA
+          or manifest.get("candidate_method") != selection.candidate_method
+          or manifest.get("candidate_family") != selection.family_selection()):
+        raise HostedError("candidate_selection_mismatch", "family selection differs from the frozen root manifest")
+    if is_model:
+        from .model_admission import require_model_authorization
+        if any(not isinstance(manifest.get(key), Mapping) for key in ("base_repository", "head_repository", "suite", "baseline")):
+            raise HostedError("candidate_selection_mismatch", "prepared model source and evaluation identities are invalid")
+        require_model_authorization(manifest.get("model_runtime"), team_id=manifest.get("team_id"),
+            base_repository_id=manifest.get("base_repository", {}).get("id"),
+            head_repository_id=manifest.get("head_repository", {}).get("id"),
+            suite=manifest.get("suite", {}).get("id"), baseline=manifest.get("baseline", {}).get("id"))
+        if manifest.get("requested_runtime_profile") != selection.config.runtime_profile:
+            raise HostedError("candidate_selection_mismatch", "requested model runtime differs from selected configuration")
+    elif "model_runtime" in manifest:
+        raise HostedError("candidate_selection_mismatch", "legacy candidate cannot inherit model admission")
+    files = manifest.get("files")
+    if (not isinstance(files, list) or any(not isinstance(item, Mapping) for item in files)
+            or any(type(item.get("path")) is not str for item in files)
+            or len(files) != len(selection.config.source_files) + 1
+            or {item.get("path") for item in files} != {"sphynx.toml", *selection.config.source_files}
+            or manifest.get("candidate_configuration") != selection.config.to_dict()
+            or manifest.get("configuration_digest") != selection.config.digest):
+        raise HostedError("candidate_selection_mismatch", "configuration or declared source closure differs from the selected method")
+    return selection