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

sphynx/rerank_workflow.py

@@ -0,0 +1,424 @@
+"""Native adapter for the installed illustrative frozen-pool reranking suite.
+
+RAG schemas, fixed case membership, local policy and metric layouts belong in
+this adapter. Shared orchestration uses WorkflowBackend and native references.
+The adapter preserves local_unverified evidence; admission is not a sandbox or
+verification of candidate source bytes.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from .assessment_contracts import ASSESSMENT_VIEW_SCHEMA, Assessment, CaseView
+from .contracts import (
+    PACK_ID, REQUEST_SCHEMA_VERSION, CandidateSpec, CaseReferences, EvidenceGroup,
+    ReferenceCandidate, build_candidate_request, canonical_json, validate_candidate_request,
+)
+from .evals import ResolvedInvocation, require_legacy_rerank, resolve_eval
+from .evidence import RunRef, read_run_manifest, sha256_bytes
+from .metrics import GRADER_RELEASE, METRIC_RELEASE, metric_definitions
+from .packs import check_candidate, get_pack
+from .rag import FIXTURE_SHA256, load_rag_rerank_pack, validate_dataset_v2
+from .results import Comparison, EvaluationRef, ResultError, Scorecard
+from .results import compare as native_compare
+from .results import grade as native_grade
+from .results import report as native_report
+from .runner import run as native_run
+from .workflow_contracts import (
+    AdmissionBinding, BackendDescriptor, Criterion, Dataset, DatasetDefinition,
+    EvaluatorDefinition, MetricSpec, PayloadSchema, PlanBinding,
+    ReferenceBinding, ResolvedBinding, SuiteDefinition, WorkflowContractError,
+    contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+
+RERANK_BACKEND_ID = "sphynx.rerank.local"
+RERANK_REFERENCE_SCHEMA = "sphynx.rag.rerank.case-references.v1"
+_AGGREGATION_POLICY_ID = "sphynx.rerank.aggregate.v1"
+_COMPARISON_POLICY_ID = "sphynx.rerank.paired-comparison.v1"
+_DESCRIPTOR = BackendDescriptor(
+    backend_id=RERANK_BACKEND_ID, version="v1",
+    implementation_id="sphynx.rag.rerank.native-adapter.v1",
+    capabilities=("sphynx.case-inputs.v1", "sphynx.local-subprocess.v1",
+                  "sphynx.saved-assessment.v1", "sphynx.native-report.v1",
+                  "sphynx.paired-comparison.v1"),
+    supported_scopes=("component",), supported_modes=("local",), suite_ids=(PACK_ID,),
+    metadata={"native_pack_id": PACK_ID, "trust_tier": "local_unverified",
+              "illustrative": True, "candidate_source_bytes_verified": False},
+)
+
+
+def _candidate_identity(candidate: CandidateSpec) -> dict[str, str]:
+    # The native v1 identity pins argv metadata, not executable/source bytes.
+    return {"name": candidate.name, "version": candidate.version,
+            "interface_version": candidate.interface_version,
+            "argv_sha256": sha256_bytes(canonical_json(list(candidate.argv)).encode("utf-8"))}
+
+
+def _case_view(case: Any) -> CaseView:
+    request = build_candidate_request(case, PACK_ID)
+    return CaseView(
+        case.case_id, REQUEST_SCHEMA_VERSION, request.to_dict(),
+        metadata={"dataset_id": case.dataset_id, "dataset_version": case.dataset_version,
+                  "pool_digest": case.pool_digest, "split": case.split,
+                  "split_group_id": case.split_group_id, "cluster_id": case.cluster_id},
+    )
+
+
+class RerankBackend:
+    """Delegate the common flow to unchanged native reranking operations."""
+
+    @property
+    def descriptor(self) -> BackendDescriptor:
+        return _DESCRIPTOR
+
+    def describe(self, suite_id: str) -> SuiteDefinition:
+        """Read declared metadata only; do not load cases or grading labels."""
+        if suite_id != PACK_ID:
+            raise WorkflowContractError(f"no native reranking adapter for suite {suite_id!r}")
+        invocation = resolve_eval(suite_id)
+        descriptor = get_pack(suite_id)
+        artifact = invocation.artifacts[0]
+        dataset = DatasetDefinition(
+            dataset_id=str(artifact["ref"]).rsplit("@", 1)[0],
+            version=artifact["version"], provider_id="sphynx.rerank.frozen-pool.v1",
+            input_schema_id=REQUEST_SCHEMA_VERSION, reference_schema_id=RERANK_REFERENCE_SCHEMA,
+            selection={"membership": "all_installed_cases", "order": "native_pack_order"},
+            identity={"artifact_ref": artifact["ref"], "sha256": artifact["digest"]},
+        )
+        return SuiteDefinition(
+            suite_id=suite_id, version=descriptor.pack_release,
+            backend_id=self.descriptor.backend_id, title=descriptor.title,
+            criterion_ids=invocation.definition.metric_ids,
+            evaluator_ids=(GRADER_RELEASE,), metric_ids=invocation.definition.metric_ids,
+            required_capabilities=("sphynx.local-subprocess.v1", "sphynx.saved-assessment.v1"),
+            datasets=(dataset,),
+            metadata={"native_definition_digest": invocation.definition.definition_digest,
+                      "native_metric_criterion_mapping": True,
+                      "native_execution_policy": asdict(descriptor.execution_policy),
+                      "case_count": descriptor.case_count, "illustrative": True,
+                      "trust_tier": "local_unverified"},
+        )
+
+    def _suite(self, suite: SuiteDefinition) -> None:
+        if not isinstance(suite, SuiteDefinition):
+            raise WorkflowContractError("native reranking suite must be SuiteDefinition")
+        expected = self.describe(suite.suite_id)
+        if suite.definition_digest != expected.definition_digest:
+            raise WorkflowContractError("suite definition differs from the native reranking adapter")
+
+    def _plan(self, plan: PlanBinding) -> None:
+        if not isinstance(plan, PlanBinding):
+            raise WorkflowContractError("native reranking plan must be PlanBinding")
+        self._suite(plan.suite)
+        if plan.scope not in self.descriptor.supported_scopes or plan.mode not in self.descriptor.supported_modes:
+            raise WorkflowContractError("this suite supports only scope='component', mode='local'")
+        if not isinstance(plan.candidate, CandidateSpec):
+            raise WorkflowContractError("native reranking candidate must be CandidateSpec")
+        check = check_candidate(plan.candidate, plan.suite.suite_id)
+        if not check.compatible or not check.pack_runnable:
+            raise WorkflowContractError("; ".join(check.reasons) or "native suite cannot execute")
+        if plan.runtime:
+            raise WorkflowContractError("native reranking does not accept runtime overrides")
+
+    def cases(self, suite: SuiteDefinition) -> tuple[CaseView, ...]:
+        self._suite(suite)
+        return tuple(_case_view(case) for case in load_rag_rerank_pack().cases)
+
+    def resolve(self, plan: PlanBinding) -> ResolvedBinding:
+        self._plan(plan)
+        invocation = resolve_eval(plan.suite.suite_id, plan.parameters)
+        return ResolvedBinding(
+            identity={"backend": self.descriptor.to_dict(),
+                      "suite_id": plan.suite.suite_id,
+                      "suite_definition_digest": plan.suite.definition_digest,
+                      "scope": plan.scope, "mode": plan.mode, "runtime": dict(plan.runtime),
+                      "candidate": _candidate_identity(plan.candidate),
+                      "native_invocation": invocation.to_dict(),
+                      "candidate_source_bytes_verified": False},
+            native_ref=invocation,
+        )
+
+    def _resolution(self, plan: PlanBinding, resolved: ResolvedBinding) -> None:
+        if not isinstance(resolved, ResolvedBinding) or not isinstance(resolved.native_ref, ResolvedInvocation):
+            raise WorkflowContractError("native reranking requires a native resolved invocation")
+        expected = self.resolve(plan)
+        if (resolved.resolution_digest != expected.resolution_digest
+                or resolved.native_ref.invocation_digest != expected.native_ref.invocation_digest):
+            raise WorkflowContractError("resolved suite or candidate identity changed; resolve the plan again")
+
+    def _facts(self, plan: PlanBinding, resolved: ResolvedBinding) -> dict[str, Any]:
+        self._resolution(plan, resolved)
+        admitted = require_legacy_rerank(plan.suite.suite_id, plan.parameters)
+        if admitted.invocation_digest != resolved.native_ref.invocation_digest:
+            raise WorkflowContractError("native admission differs from the resolved invocation")
+        # A cached successful load cannot establish the identity of current bytes.
+        payload = resources.files("sphynx").joinpath("data", "rag-rerank-v1.json").read_bytes()
+        digest = sha256_bytes(payload)
+        if digest != "sha256:" + FIXTURE_SHA256:
+            raise WorkflowContractError("installed suite bytes differ from the pinned release")
+        pack = load_rag_rerank_pack()
+        if pack.dataset_digest != digest:
+            raise WorkflowContractError("loaded suite identity differs from verified asset bytes")
+        verified_cases, _, _ = validate_dataset_v2(json.loads(payload))
+        if pack.cases != verified_cases:
+            raise WorkflowContractError("loaded case membership differs from verified suite bytes")
+        descriptor = get_pack(plan.suite.suite_id)
+        if descriptor != pack.descriptor:
+            raise WorkflowContractError("suite descriptor differs from the loaded native pack")
+        return {"dataset_digest": digest, "descriptor_digest": contract_digest(asdict(descriptor)),
+                "case_ids": [case.case_id for case in pack.cases]}
+
+    def admit(self, plan: PlanBinding, resolved: ResolvedBinding) -> AdmissionBinding:
+        return AdmissionBinding(
+            resolution_digest=resolved.resolution_digest, facts=self._facts(plan, resolved),
+            trust_tier="local_unverified", artifact_bytes_verified=True,
+            candidate_source_bytes_verified=False,
+        )
+
+    def recheck(self, plan: PlanBinding, resolved: ResolvedBinding, admission: AdmissionBinding) -> None:
+        if not isinstance(admission, AdmissionBinding):
+            raise WorkflowContractError("native reranking admission must be AdmissionBinding")
+        expected = self.admit(plan, resolved)
+        if contract_digest(admission.to_dict()) != contract_digest(expected.to_dict()):
+            raise WorkflowContractError("admitted suite has changed; resolve and admit a new plan")
+
+    def execute(self, plan: PlanBinding, resolved: ResolvedBinding, admission: AdmissionBinding,
+                output_dir: str | Path | None) -> RunRef:
+        self.recheck(plan, resolved, admission)
+        if output_dir is None:
+            raise WorkflowContractError("native reranking requires an output directory")
+        return native_run(plan.candidate, plan.suite.suite_id, output_dir,
+                          parameters=plan.parameters if plan.parameters else None)
+
+    def accepts_reference(self, native_ref: Any, kind: str) -> bool:
+        if kind == "run":
+            return isinstance(native_ref, RunRef) and native_ref.pack_id == PACK_ID
+        if kind == "grading":
+            if not isinstance(native_ref, EvaluationRef):
+                return False
+            if native_ref.pack_id == PACK_ID:
+                return True
+            # A wholly unreadable native run cannot supply a pack or grading
+            # path. Keep its explicit error diagnostic for an already-bound
+            # backend; this does not recognize foreign packs or successful data.
+            return (native_ref.pack_id is None and native_ref.path is None
+                    and native_ref.status in {"corrupt", "incompatible", "unsupported_schema", "grader_error"})
+        return False
+
+    def _reference(self, native_ref: Any, kind: str) -> None:
+        if not self.accepts_reference(native_ref, kind):
+            raise WorkflowContractError(f"unsupported native reranking {kind} reference")
+
+    def reference(self, native_ref: Any, kind: str) -> ReferenceBinding:
+        self._reference(native_ref, kind)
+        if kind == "run":
+            manifest = read_run_manifest(native_ref)
+            return ReferenceBinding(
+                record_id=native_ref.run_id, run_id=native_ref.run_id,
+                status=manifest["status"], trust_tier="local_unverified",
+                metadata={"native_pack_id": native_ref.pack_id, "illustrative": True},
+            )
+        return ReferenceBinding(
+            record_id=native_ref.evaluation_id, run_id=native_ref.run_id,
+            status=native_ref.status, trust_tier="local_unverified",
+            metadata={"native_pack_id": native_ref.pack_id, "reason": native_ref.reason,
+                      "illustrative": True},
+        )
+
+    def assess(self, native_run: Any) -> EvaluationRef:
+        self._reference(native_run, "run")
+        return native_grade(native_run)
+
+    def report(self, native_grading: Any) -> Scorecard:
+        self._reference(native_grading, "grading")
+        if native_grading.path is None:
+            raise WorkflowContractError(native_grading.reason or "no readable saved grading record")
+        return native_report(native_grading)
+
+    def assessments(self, native_grading: Any, case_id: str | None = None) -> tuple[Assessment, ...]:
+        self._reference(native_grading, "grading")
+        if native_grading.path is None:
+            raise WorkflowContractError(native_grading.reason or "no readable saved grading record")
+        path = native_grading.path / "judgments.jsonl"
+        try:
+            raw = path.read_bytes()
+        except OSError as exc:
+            raise ResultError(f"cannot read saved assessments: {exc}") from exc
+        data = self.report(native_grading).to_dict()
+        if path.read_bytes() != raw:
+            raise WorkflowContractError("saved assessments changed during verification; read the report again")
+        rows = [json.loads(line) for line in raw.decode("utf-8").splitlines()]
+        if case_id is not None and case_id not in {row["case_id"] for row in rows}:
+            raise WorkflowContractError(f"case {case_id!r} is not in this report")
+        assessments = []
+        for row in rows:
+            if case_id is not None and row["case_id"] != case_id:
+                continue
+            for metric_id, value in row["values"].items():
+                reason = row["undefined_reasons"].get(metric_id) or row["reason"]
+                if value is not None:
+                    availability = "available"
+                elif row["status"] == "grader_error":
+                    availability = "error"
+                elif row["status"] in {"corrupt", "incompatible", "unsupported_schema"}:
+                    availability = "unavailable"
+                elif reason in {"unsupported_query", "zero_ideal_dcg"}:
+                    availability = "undefined"
+                else:
+                    availability = "missing"
+                assessments.append(Assessment(
+                    criterion_id=metric_id, evaluator_id=data["releases"]["grader_release"],
+                    case_id=row["case_id"], kind="score", availability=availability,
+                    value=value, reason=reason,
+                    evidence_ids=(row["capture_id"],) if row["capture_id"] else (),
+                    run_id=row["run_id"], grading_id=row["evaluation_id"],
+                    trial=row["trial_index"], attempt=1,
+                ))
+        return tuple(assessments)
+
+    def compare(self, baseline_grading: Any, candidate_grading: Any) -> Comparison:
+        self._reference(baseline_grading, "grading")
+        self._reference(candidate_grading, "grading")
+        return native_compare(baseline_grading, candidate_grading)
+
+    def compare_view(self, baseline_grading, candidate_grading):
+        from ._comparison_adapters import _rerank_view, _sources
+        native = self.compare(baseline_grading, candidate_grading).to_dict()
+        reports = [self.report(ref).to_dict() for ref in (baseline_grading, candidate_grading)]
+        conditions = [{key: report[key] for key in ("identity", "releases", "candidate")}
+                      for report in reports]
+        return _rerank_view(_sources(self, baseline_grading, candidate_grading, conditions=conditions),
+                            native, {item.metric_id: _metric_spec(item) for item in metric_definitions()})
+
+
+def _validate_native_request(value: Any) -> None:
+    """Wrap the strict typed native parser without changing validator return policy."""
+    validate_candidate_request(value)
+
+
+def _validate_native_references(value: Any) -> None:
+    """Validate the reference structure without loading or authorizing native labels.
+
+    Exact case/cohort/label binding remains the native grader's responsibility.
+    The public default provider never supplies a reference loader or grant.
+    """
+    if type(value) is not dict or set(value) != {"case_id", "label_authority", "candidates", "evidence_groups"}:
+        raise WorkflowContractError("native references require the exact CaseReferences fields")
+    if type(value["candidates"]) is not list or not value["candidates"]:
+        raise WorkflowContractError("native references require a nonempty candidate array")
+    if type(value["evidence_groups"]) is not list:
+        raise WorkflowContractError("native references require an evidence-group array")
+    candidate_fields = {"candidate_id", "relevance_grade", "evidence_group_ids"}
+    group_fields = {"evidence_group_id", "description", "required", "acceptable_candidate_ids"}
+    if any(type(item) is not dict or set(item) != candidate_fields for item in value["candidates"]):
+        raise WorkflowContractError("native reference candidates have unsupported fields")
+    if any(type(item) is not dict or set(item) != group_fields for item in value["evidence_groups"]):
+        raise WorkflowContractError("native evidence groups have unsupported fields")
+    references = CaseReferences(
+        value["case_id"], value["label_authority"],
+        tuple(ReferenceCandidate(**item) for item in value["candidates"]),
+        tuple(EvidenceGroup(**item) for item in value["evidence_groups"]),
+    )
+    candidates = {item.candidate_id: item for item in references.candidates}
+    groups = {item.evidence_group_id: item for item in references.evidence_groups}
+    if any(not set(item.evidence_group_ids).issubset(groups) for item in references.candidates):
+        raise WorkflowContractError("native reference candidate names an unknown evidence group")
+    if any(not set(item.acceptable_candidate_ids).issubset(candidates) for item in references.evidence_groups):
+        raise WorkflowContractError("native evidence group names an unknown candidate")
+    if any((group_id in candidate.evidence_group_ids) != (candidate_id in group.acceptable_candidate_ids)
+           for candidate_id, candidate in candidates.items() for group_id, group in groups.items()):
+        raise WorkflowContractError("native candidate and evidence-group links must be reciprocal")
+
+
+def _validate_builtin_assessment(value: Any) -> None:
+    fields = {"schema_version", "criterion_id", "evaluator_id", "case_id", "kind", "availability",
+              "value", "reason", "evidence_ids", "run_id", "grading_id", "trial", "attempt"}
+    if type(value) is not dict or set(value) != fields or value["schema_version"] != ASSESSMENT_VIEW_SCHEMA:
+        raise WorkflowContractError("builtin assessments require the exact v1 view fields")
+    if value["kind"] not in {"assertion", "score", "label"}:
+        raise WorkflowContractError("builtin assessment schema does not accept custom payload kinds")
+    Assessment(**{key: item for key, item in value.items() if key != "schema_version"})
+
+
+def _metric_spec(definition):
+    return MetricSpec(definition.metric_id, definition.release, definition.unit, definition.direction,
+        aggregation_policy=_AGGREGATION_POLICY_ID, comparison_policy=_COMPARISON_POLICY_ID,
+        population={"eligible_population": definition.eligible_population,
+                    "undefined_policy": definition.undefined_policy, "missing_policy": definition.missing_policy},
+        metadata={"native_aggregation": definition.aggregation, "primary": definition.primary})
+
+
+def register_rerank_backend(registry: WorkflowRegistry) -> RerankBackend:
+    """Register this adapter and its exact declared contracts without reading assets.
+
+    The registry must explicitly permit the native bare metric and dataset IDs.
+    ``build_rerank_registry`` supplies that narrow legacy-ID list. Registration
+    is not admission, does not run validators, and never loads grading labels.
+    Existing bindings are not silently replaced; duplicate registration fails.
+    """
+    if not isinstance(registry, WorkflowRegistry):
+        raise WorkflowContractError("native reranking registration requires a WorkflowRegistry")
+    backend = RerankBackend()
+    suite = backend.describe(PACK_ID)
+    registry.register_backend(backend)
+    input_schema = registry.register_schema(PayloadSchema(
+        REQUEST_SCHEMA_VERSION, "v1", "sphynx.contracts.validate_candidate_request.v1",
+        _validate_native_request,
+        metadata={"native_protocol": REQUEST_SCHEMA_VERSION, "candidate_permitted": True},
+    ))
+    reference_schema = registry.register_schema(PayloadSchema(
+        RERANK_REFERENCE_SCHEMA, "v1", "sphynx.rerank.native-case-references.v1",
+        _validate_native_references,
+        metadata={"access": "backend_authorized_only", "native_grader_binds_exact_labels": True},
+    ))
+    registry.register_schema(PayloadSchema(
+        ASSESSMENT_VIEW_SCHEMA, "v1", "sphynx.assessment-contracts.builtin-v1",
+        _validate_builtin_assessment,
+        metadata={"kinds": ["assertion", "score", "label"], "native_records_authoritative": True},
+    ))
+    registry.register_provider(Dataset(
+        definition=suite.datasets[0], input_schema=input_schema,
+        case_source=lambda selected: backend.cases(suite), reference_schema=reference_schema,
+    ))
+    registry.register_policy(
+        _AGGREGATION_POLICY_ID, version="v1",
+        implementation_id=METRIC_RELEASE + ".aggregate-case-metrics", kind="aggregation",
+        metadata={"execution": "backend_owned", "native_operation": "sphynx.metrics.aggregate_case_metrics",
+                  "preserve_eligible_missing_undefined_populations": True},
+    )
+    registry.register_policy(
+        _COMPARISON_POLICY_ID, version="v1", implementation_id="sphynx.results.compare.v1",
+        kind="comparison", metadata={"execution": "backend_owned",
+                                     "native_operation": "sphynx.results.compare",
+                                     "delta_direction": "candidate_minus_baseline"},
+    )
+    for definition in metric_definitions():
+        registry.register_criterion(Criterion(
+            definition.metric_id, definition.release, definition.metric_id,
+            configuration={"native_metric_mapping": True,
+                           "dimension": "measurement" if definition.metric_id == "runner_latency_ms" else "quality"},
+        ))
+        registry.register_metric(_metric_spec(definition))
+    registry.register_evaluator(EvaluatorDefinition(
+        GRADER_RELEASE, "v1", "sphynx.results.grade:" + GRADER_RELEASE,
+        criterion_ids=suite.criterion_ids, assessment_schema_ids=(ASSESSMENT_VIEW_SCHEMA,),
+        metric_ids=suite.metric_ids, required_capabilities=("sphynx.saved-assessment.v1",),
+        configuration={"execution": "backend_owned", "native_grading_records_authoritative": True},
+    ))
+    registry.register_suite(suite)
+    return backend
+
+
+def build_rerank_registry() -> WorkflowRegistry:
+    """Return a fresh registry for the built-in native reranking adapter."""
+    suite = RerankBackend().describe(PACK_ID)
+    registry = WorkflowRegistry(legacy_ids=(*suite.criterion_ids, *suite.metric_ids,
+                                          *(dataset.dataset_id for dataset in suite.datasets)))
+    register_rerank_backend(registry)
+    return registry

sphynx/research_candidate.py

@@ -0,0 +1,190 @@
+"""Pinned operator-side candidate entry point for local research parity.
+
+This protocol uses an installed SDK and owner-provided assets. It is not an
+admission into the hosted worker's smaller repository/runtime allowlist.
+Configuration contains file references and digests, never credential values.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+from .contracts import CandidateSpec, ContractError, canonical_json, validate_candidate_request
+from .integration_contracts import CandidateConfiguration, ComparisonIdentity, _freeze, _wire, require_digest, value_digest
+from .model_adapters import create_model_scorer
+from .recorded_scores import create_recorded_scorer
+
+SCHEMA = "sphynx.research-candidate.v1"
+INTERFACE = "sphynx.rag.rerank.v1"
+
+
+def _json(raw):
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise ContractError("duplicate JSON field")
+            result[key] = value
+        return result
+    def invalid(value):
+        raise ContractError("nonfinite JSON value")
+    return json.loads(raw, object_pairs_hook=pairs, parse_constant=invalid)
+
+
+def _read(path, expected, limit=128 * 1024 * 1024):
+    require_digest(expected, "asset digest")
+    source = Path(path).expanduser().resolve(strict=True)
+    if not source.is_file() or source.stat().st_size > limit:
+        raise ContractError("asset must be a bounded file")
+    raw = source.read_bytes()
+    if "sha256:" + hashlib.sha256(raw).hexdigest() != expected:
+        raise ContractError("asset bytes differ from pinned digest")
+    return _json(raw)
+
+
+def _fields(value, keys):
+    if not isinstance(value, dict) or set(value) != set(keys):
+        raise ContractError("research candidate configuration fields differ")
+    _freeze(value, reject_secrets=True)
+    return value
+
+
+def _source(value):
+    if not isinstance(value, dict):
+        raise ContractError("source scorer configuration required")
+    if value.get("kind") == "offline_model":
+        _fields(value, ("kind", "model_id", "snapshot_path", "snapshot_digest", "threads"))
+        return create_model_scorer(value["model_id"], value["snapshot_path"], value["snapshot_digest"], threads=value["threads"])
+    if value.get("kind") == "recorded_model":
+        _fields(value, ("kind", "recording_path", "recording_digest", "requests_path", "requests_digest"))
+        artifact = _read(value["recording_path"], value["recording_digest"])
+        requests = _read(value["requests_path"], value["requests_digest"])
+        if not isinstance(requests, list):
+            raise ContractError("recorded source requires a complete ordered request array")
+        checked = [validate_candidate_request(request).to_dict() for request in requests]
+        return create_recorded_scorer(value["recording_path"], value["recording_digest"],
+            identity=ComparisonIdentity.from_dict(artifact["identity"]), requests=checked, expected_model=artifact["model"])
+    raise ContractError("source kind must be offline_model or recorded_model")
+
+
+class RecordedFeatures:
+    """Complete request-bound, label-free learned features; no guessed joins."""
+    def __init__(self, config):
+        from .learned_rerank import FEATURE_NAMES
+        _fields(config, ("path", "digest"))
+        self.path, self.digest = config["path"], config["digest"]
+        artifact = _read(self.path, self.digest)
+        _fields(artifact, ("schema_version", "cases"))
+        if artifact["schema_version"] != "sphynx.rerank-features.v1" or not isinstance(artifact["cases"], list):
+            raise ContractError("unsupported recorded feature schema")
+        rows = {}
+        for row in artifact["cases"]:
+            _fields(row, ("case_id", "request_digest", "features"))
+            require_digest(row["request_digest"], "feature request digest")
+            if not isinstance(row["case_id"], str) or row["case_id"] in rows or not isinstance(row["features"], dict):
+                raise ContractError("feature case identity differs")
+            for features in row["features"].values():
+                _fields(features, FEATURE_NAMES)
+                if any(value is not None and (type(value) not in (int, float)) for value in features.values()):
+                    raise ContractError("feature values must be finite numbers or explicit null")
+            rows[row["case_id"]] = row
+        self._rows = _freeze(rows)
+        self.configuration = CandidateConfiguration("recorded-features-v1", "sphynx.rerank-features.v1",
+            "sha256:" + hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), {"asset_digest": self.digest}, "recorded")
+
+    def __call__(self, request):
+        _read(self.path, self.digest)
+        row = self._rows.get(request["case_id"])
+        if row is None or row["request_digest"] != value_digest(request):
+            raise ContractError("feature recording request differs")
+        if set(row["features"]) != {candidate["candidate_id"] for candidate in request["candidates"]}:
+            raise ContractError("feature passage membership differs")
+        return _wire(row["features"])
+
+
+def load_research_candidate(configuration_path, expected_digest):
+    """Construct a frozen reranker without loading weights or calling providers."""
+    from . import __version__
+    config = _read(configuration_path, expected_digest, 1024 * 1024)
+    _fields(config, ("schema_version", "sdk_version", "family", "method", "parameters", "sources", "fitted_state", "features"))
+    if config["schema_version"] != SCHEMA or config["sdk_version"] != __version__:
+        raise ContractError("research candidate schema or installed SDK version differs")
+    if not isinstance(config["sources"], dict) or not isinstance(config["parameters"], dict):
+        raise ContractError("research candidate sources and parameters must be objects")
+    sources = {name: _source(value) for name, value in config["sources"].items()}
+    family, method = config["family"], config["method"]
+    if family in ("statistical", "learned"):
+        for slot, source in sources.items():
+            params = source.configuration.parameters
+            model = params.get("model", params)
+            model_id = model.get("id", model.get("model_id"))
+            if model_id != {"minilm": "minilm-l6-v2", "jina": "jina-turbo-v1"}.get(slot):
+                raise ContractError("source model identity differs from selected family slot")
+            if model.get("activation") != "identity":
+                raise ContractError("family source requires raw identity-activation logits")
+    if family == "pointwise":
+        if set(sources) != {"model"} or config["parameters"] or config["fitted_state"] is not None or config["features"] is not None:
+            raise ContractError("pointwise candidate must declare exactly one source")
+        source = sources["model"]
+        if source.configuration.parameters.get("model_id", source.configuration.parameters.get("model", {}).get("id")) != method:
+            raise ContractError("selected pointwise method differs from source model")
+        return source
+    if family == "statistical":
+        from .statistical_rerank import create_statistical_scorer, METHOD_REGISTRY
+        if config["fitted_state"] is not None or config["features"] is not None or set(sources) - {"minilm", "jina"}:
+            raise ContractError("statistical source fields differ")
+        if method not in METHOD_REGISTRY:
+            raise ContractError("unknown statistical method")
+        required = set() if method in ("S1", "Dense-only") else ({"minilm", "jina"} if method == "Guarded-Jina-E2"
+            else {"jina"} if method.startswith(("Jina", "S6")) or method == "S7" else {"minilm"})
+        if set(sources) != required:
+            raise ContractError("selected statistical method requires its exact source scorers")
+        return create_statistical_scorer(method, scorers=sources, parameters=config["parameters"])
+    if family == "learned":
+        from .learned_rerank import create_learned_scorer
+        from .rerank_family_contracts import load_fitted_state
+        state = _fields(config["fitted_state"], ("path", "digest"))
+        params = _fields(config["parameters"], ("evaluation_cohort_digest", "domain_id"))
+        if set(sources) != {"minilm"}:
+            raise ContractError("learned candidate requires the MiniLM source")
+        fitted = load_fitted_state(state["path"], state["digest"])
+        if fitted.method != method:
+            raise ContractError("selected learned method differs from fitted state")
+        return create_learned_scorer(fitted, minilm_scorer=sources["minilm"],
+            feature_provider=RecordedFeatures(config["features"]), **params)
+    raise ContractError("unsupported research candidate family")
+
+
+def make_research_candidate(configuration_path, expected_digest):
+    """Return the existing SDK subprocess protocol with pinned configuration."""
+    scorer = load_research_candidate(configuration_path, expected_digest)
+    return CandidateSpec(scorer.configuration.configuration_id, scorer.configuration.digest,
+        (sys.executable, "-m", "sphynx.research_candidate", str(Path(configuration_path).resolve()), expected_digest,
+         scorer.configuration.digest), INTERFACE)
+
+
+def protocol_main(argv=None):
+    try:
+        args = sys.argv[1:] if argv is None else argv
+        if len(args) not in (2, 3):
+            raise ContractError("expected configuration path, exact digest and optional resolved scorer digest")
+        scorer = load_research_candidate(args[0], args[1])
+        if len(args) == 3:
+            require_digest(args[2], "resolved scorer digest")
+            if scorer.configuration.digest != args[2]:
+                raise ContractError("resolved scorer configuration changed before execution")
+        raw = sys.stdin.buffer.read(1024 * 1024 + 1)
+        if len(raw) > 1024 * 1024:
+            raise ContractError("request too large")
+        request = validate_candidate_request(_json(raw)).to_dict()
+        print(canonical_json(scorer(request)), flush=True)
+        return 0
+    except Exception as exc:
+        print("research_candidate_failure:" + type(exc).__name__, file=sys.stderr, flush=True)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(protocol_main())