solverpilot 0.1__py3-none-any.whl

solverpilot/backends/scipy_vendored_highs_dev.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import importlib.util
+
+import numpy as np
+from scipy import sparse
+
+from solverpilot.capabilities import BackendManifest, Capability, SupportLevel
+from solverpilot.problem import LinearProblem, ObjectiveSense, QuadraticProblem, VariableDomain
+from solverpilot.problem.quadratic import require_confirmed_convexity
+
+from .base import BackendSolveResult, BackendUnavailableError
+
+
+def _available() -> bool:
+    return importlib.util.find_spec("scipy.optimize._highspy._core") is not None
+
+
+def _status_name(core, status) -> str:
+    mapping = {
+        core.HighsModelStatus.kOptimal: "optimal",
+        core.HighsModelStatus.kInfeasible: "infeasible",
+        core.HighsModelStatus.kUnbounded: "unbounded",
+        core.HighsModelStatus.kUnboundedOrInfeasible: "infeasible_or_unbounded",
+        core.HighsModelStatus.kTimeLimit: "limit_no_solution",
+        core.HighsModelStatus.kIterationLimit: "limit_no_solution",
+        core.HighsModelStatus.kSolutionLimit: "limit_no_solution",
+        core.HighsModelStatus.kObjectiveBound: "limit_no_solution",
+        core.HighsModelStatus.kObjectiveTarget: "limit_no_solution",
+        core.HighsModelStatus.kInterrupt: "limit_no_solution",
+        core.HighsModelStatus.kModelError: "solver_error",
+        core.HighsModelStatus.kSolveError: "solver_error",
+        core.HighsModelStatus.kPresolveError: "solver_error",
+        core.HighsModelStatus.kPostsolveError: "solver_error",
+        core.HighsModelStatus.kLoadError: "solver_error",
+        core.HighsModelStatus.kMemoryLimit: "solver_error",
+    }
+    return mapping.get(status, "unknown")
+
+
+def _ok(core, status) -> bool:
+    return status in {core.HighsStatus.kOk, core.HighsStatus.kWarning}
+
+
+def _linear_csc(problem: LinearProblem) -> sparse.csc_matrix:
+    A = problem.A.tocsc(copy=True)
+    A.sort_indices()
+    return A
+
+
+def _lower_hessian_csc(problem: QuadraticProblem) -> sparse.csc_matrix:
+    P = sparse.tril(problem.P, format="csc")
+    P.sort_indices()
+    return P
+
+
+
+
+@dataclass(frozen=True, slots=True)
+class HighsDevIISResult:
+    valid: bool
+    row_indices: tuple[int, ...]
+    row_bound_statuses: tuple[int, ...]
+    col_indices: tuple[int, ...]
+    col_bound_statuses: tuple[int, ...]
+    strategy: int
+
+@dataclass(slots=True)
+class ScipyVendoredHighsDevBackend:
+    """Stateful development-only HiGHS backend using SciPy's private vendored bindings.
+
+    This class exists only to *verify architecture and reuse semantics* in environments
+    where the public ``highspy`` package cannot be installed.  It must never be treated
+    as a production dependency: ``scipy.optimize._highspy`` is private API and may change
+    without notice.
+
+    For continuous LPs with unchanged structure, the backend updates the existing model,
+    restores the previous valid basis explicitly, and reruns HiGHS.  For MILPs with
+    unchanged structure it injects the previous incumbent as a solution start.  Structural
+    changes force a rebuild.  QPs are solved natively but are rebuilt in this M3 verifier.
+    """
+
+    time_limit_s: float | None = None
+    threads: int | None = None
+    solver: str | None = None
+    presolve: bool | None = None
+    _highs: object | None = field(default=None, init=False, repr=False)
+    _last_problem: LinearProblem | QuadraticProblem | None = field(default=None, init=False, repr=False)
+    _last_x: np.ndarray | None = field(default=None, init=False, repr=False)
+
+    @property
+    def manifest(self) -> BackendManifest:
+        version = None
+        if self.is_available():
+            from scipy.optimize._highspy import _core as core
+            version = f"{core.HIGHS_VERSION_MAJOR}.{core.HIGHS_VERSION_MINOR}.{core.HIGHS_VERSION_PATCH}-scipy-vendored"
+        return BackendManifest(
+            name="scipy-vendored-highs-native-dev",
+            version=version,
+            capabilities={
+                Capability.LP: SupportLevel.NATIVE,
+                Capability.CONVEX_QP: SupportLevel.NATIVE,
+                Capability.MILP: SupportLevel.NATIVE,
+                Capability.MIP_START: SupportLevel.NATIVE,
+                Capability.PRIMAL_START: SupportLevel.NATIVE,
+                Capability.DUAL_START: SupportLevel.UNSUPPORTED,
+                Capability.BASIS_START: SupportLevel.NATIVE,
+                Capability.SAME_SPARSITY_DATA_UPDATE: SupportLevel.NATIVE,
+                Capability.STRUCTURAL_INCREMENTAL_UPDATE: SupportLevel.UNSUPPORTED,
+                Capability.NATIVE_REOPTIMIZATION: SupportLevel.NATIVE,
+                Capability.CALLBACK_PROGRESS: SupportLevel.UNKNOWN,
+                Capability.IIS: SupportLevel.NATIVE,
+                Capability.INFEASIBILITY_CERTIFICATE: SupportLevel.UNKNOWN,
+            },
+            metadata={
+                "native_adapter": True,
+                "stateful": True,
+                "development_only": True,
+                "private_scipy_api": True,
+                "do_not_register_by_default": True,
+            },
+        )
+
+    def is_available(self) -> bool:
+        return _available()
+
+    def _new_highs(self):
+        if not self.is_available():
+            raise BackendUnavailableError("SciPy vendored HiGHS bindings are unavailable")
+        from scipy.optimize._highspy import _core as core
+        h = core._Highs()
+        h.setOptionValue("output_flag", False)
+        if self.time_limit_s is not None:
+            if self.time_limit_s <= 0:
+                raise ValueError("time_limit_s must be positive")
+            h.setOptionValue("time_limit", float(self.time_limit_s))
+        if self.threads is not None:
+            if self.threads <= 0:
+                raise ValueError("threads must be positive")
+            h.setOptionValue("threads", int(self.threads))
+        if self.solver is not None:
+            h.setOptionValue("solver", str(self.solver))
+        if self.presolve is not None:
+            h.setOptionValue("presolve", "on" if self.presolve else "off")
+        return core, h
+
+    @staticmethod
+    def _make_lp(core, problem: LinearProblem):
+        lp = core.HighsLp()
+        lp.num_col_ = problem.n_variables
+        lp.num_row_ = problem.n_constraints
+        lp.col_cost_ = np.asarray(problem.c, dtype=np.float64)
+        lp.col_lower_ = np.asarray(problem.variable_lower, dtype=np.float64)
+        lp.col_upper_ = np.asarray(problem.variable_upper, dtype=np.float64)
+        lp.row_lower_ = np.asarray(problem.constraint_lower, dtype=np.float64)
+        lp.row_upper_ = np.asarray(problem.constraint_upper, dtype=np.float64)
+        lp.sense_ = core.ObjSense.kMinimize if problem.objective_sense is ObjectiveSense.MINIMIZE else core.ObjSense.kMaximize
+        lp.offset_ = float(problem.objective_offset)
+        A = _linear_csc(problem)
+        lp.a_matrix_.format_ = core.MatrixFormat.kColwise
+        lp.a_matrix_.start_ = np.asarray(A.indptr, dtype=np.int32)
+        lp.a_matrix_.index_ = np.asarray(A.indices, dtype=np.int32)
+        lp.a_matrix_.value_ = np.asarray(A.data, dtype=np.float64)
+        if problem.has_integer_variables:
+            lp.integrality_ = [
+                core.HighsVarType.kInteger
+                if domain in {VariableDomain.INTEGER.value, VariableDomain.BINARY.value}
+                else core.HighsVarType.kContinuous
+                for domain in problem.domains
+            ]
+        return lp
+
+    @classmethod
+    def _make_model(cls, core, problem: LinearProblem | QuadraticProblem):
+        if isinstance(problem, QuadraticProblem):
+            model = core.HighsModel()
+            model.lp_ = cls._make_lp(core, problem.linear)
+            P = _lower_hessian_csc(problem)
+            model.hessian_.dim_ = problem.n_variables
+            model.hessian_.format_ = core.HessianFormat.kTriangular
+            model.hessian_.start_ = np.asarray(P.indptr, dtype=np.int32)
+            model.hessian_.index_ = np.asarray(P.indices, dtype=np.int32)
+            model.hessian_.value_ = np.asarray(P.data, dtype=np.float64)
+            return model
+        return cls._make_lp(core, problem)
+
+    def _rebuild(self, problem: LinearProblem | QuadraticProblem):
+        core, h = self._new_highs()
+        status = h.passModel(self._make_model(core, problem))
+        if not _ok(core, status):
+            raise RuntimeError(f"vendored HiGHS rejected model: {status}")
+        self._highs = h
+        return core, h
+
+    @staticmethod
+    def _apply_same_structure_lp_updates(core, h, old: LinearProblem, new: LinearProblem) -> None:
+        n = new.n_variables
+        idx = np.arange(n, dtype=np.int32)
+        status = h.changeColsCost(n, idx, np.asarray(new.c, dtype=np.float64))
+        if not _ok(core, status):
+            raise RuntimeError(f"HiGHS cost update failed: {status}")
+        status = h.changeColsBounds(
+            n,
+            idx,
+            np.asarray(new.variable_lower, dtype=np.float64),
+            np.asarray(new.variable_upper, dtype=np.float64),
+        )
+        if not _ok(core, status):
+            raise RuntimeError(f"HiGHS variable-bound update failed: {status}")
+        for i in range(new.n_constraints):
+            status = h.changeRowBounds(i, float(new.constraint_lower[i]), float(new.constraint_upper[i]))
+            if not _ok(core, status):
+                raise RuntimeError(f"HiGHS row-bound update failed at row {i}: {status}")
+        status = h.changeObjectiveOffset(float(new.objective_offset))
+        if not _ok(core, status):
+            raise RuntimeError(f"HiGHS objective-offset update failed: {status}")
+        sense = core.ObjSense.kMinimize if new.objective_sense is ObjectiveSense.MINIMIZE else core.ObjSense.kMaximize
+        status = h.changeObjectiveSense(sense)
+        if not _ok(core, status):
+            raise RuntimeError(f"HiGHS objective-sense update failed: {status}")
+
+        # Structural hash equality guarantees identical A sparsity and variable domains.
+        # Same structural hash means CSR indptr/indices are identical.  Compare the
+        # contiguous data arrays directly so the common "A unchanged" path is O(nnz)
+        # vectorized rather than O(nnz) Python scalar indexing.
+        changed = np.flatnonzero(old.A.data != new.A.data)
+        if changed.size:
+            rows = np.searchsorted(new.A.indptr[1:], changed, side="right")
+            cols = new.A.indices[changed]
+            vals = new.A.data[changed]
+            for i, j, value in zip(rows, cols, vals, strict=True):
+                status = h.changeCoeff(int(i), int(j), float(value))
+                if not _ok(core, status):
+                    raise RuntimeError(f"HiGHS coefficient update failed at ({i}, {j}): {status}")
+
+    def solve(self, problem: LinearProblem | QuadraticProblem) -> BackendSolveResult:
+        if isinstance(problem, QuadraticProblem):
+            require_confirmed_convexity(problem)
+        if not self.is_available():
+            raise BackendUnavailableError("SciPy vendored HiGHS bindings are unavailable")
+        from scipy.optimize._highspy import _core as core
+
+        reuse_applied = False
+        reuse_mode = "cold_rebuild"
+        old = self._last_problem
+        same_structure = (
+            old is not None
+            and type(old) is type(problem)
+            and old.structural_hash == problem.structural_hash
+        )
+
+        # QP data mutation is deliberately rebuilt in the M3 verifier because this private
+        # binding does not expose a stable Hessian-update contract we are willing to claim.
+        can_update_lp = same_structure and isinstance(old, LinearProblem) and isinstance(problem, LinearProblem)
+
+        if can_update_lp and self._highs is not None:
+            h = self._highs
+            basis = None
+            if not problem.has_integer_variables:
+                candidate = h.getBasis()
+                if bool(getattr(candidate, "valid", False)):
+                    basis = candidate
+            self._apply_same_structure_lp_updates(core, h, old, problem)
+            if problem.has_integer_variables and self._last_x is not None:
+                indices = np.arange(problem.n_variables, dtype=np.int32)
+                status = h.setSolution(problem.n_variables, indices, np.asarray(self._last_x, dtype=np.float64))
+                if _ok(core, status):
+                    reuse_applied = True
+                    reuse_mode = "mip_solution_start"
+            elif basis is not None:
+                status = h.setBasis(basis)
+                if _ok(core, status):
+                    reuse_applied = True
+                    reuse_mode = "explicit_basis_hot_start"
+        else:
+            core, h = self._rebuild(problem)
+
+        runtime_before = float(h.getRunTime())
+        run_status = h.run()
+        runtime_after = float(h.getRunTime())
+        if not _ok(core, run_status):
+            raise RuntimeError(f"HiGHS run failed: {run_status}")
+
+        model_status_enum = h.getModelStatus()
+        backend_status = _status_name(core, model_status_enum)
+        info = h.getInfo()
+        primal_status = h.solutionStatusToString(info.primal_solution_status)
+        if backend_status.startswith("limit") and "feasible" in primal_status.lower() and "infeasible" not in primal_status.lower():
+            backend_status = "limit_feasible"
+
+        x = None
+        if backend_status in {"optimal", "limit_feasible"}:
+            sol = h.getSolution()
+            candidate = np.asarray(list(sol.col_value), dtype=np.float64)
+            if candidate.shape == (problem.n_variables,) and np.all(np.isfinite(candidate)):
+                x = candidate
+
+        objective = None
+        objective_internal = None
+        if x is not None:
+            try:
+                candidate = float(h.getObjectiveValue())
+                if np.isfinite(candidate):
+                    objective_internal = candidate
+                    objective = candidate
+            except Exception:
+                objective_internal = None
+
+        raw = {
+            "model_status": h.modelStatusToString(model_status_enum),
+            "primal_solution_status": primal_status,
+            "simplex_iteration_count": int(getattr(info, "simplex_iteration_count", 0)),
+            "ipm_iteration_count": int(getattr(info, "ipm_iteration_count", 0)),
+            "qp_iteration_count": int(getattr(info, "qp_iteration_count", 0)),
+            "mip_node_count": int(getattr(info, "mip_node_count", 0)),
+            "reuse_applied": reuse_applied,
+            "reuse_mode": reuse_mode,
+            "same_structure": bool(same_structure),
+            "highs_run_delta_s": max(0.0, runtime_after - runtime_before),
+            "highs_runtime_cumulative_s": runtime_after,
+            "private_scipy_api": True,
+            "objective_internal": objective_internal,
+        }
+        self._last_problem = problem
+        self._last_x = None if x is None else np.array(x, copy=True)
+        return BackendSolveResult(
+            backend_status=backend_status,
+            x=x,
+            objective_reported=objective,
+            raw_statistics=raw,
+        )
+
+    def compute_iis(self, problem: LinearProblem) -> HighsDevIISResult:
+        """Development verification of native HiGHS IIS plumbing.
+
+        This is intentionally a small typed surface.  Bound-status integers are kept
+        solver-native because the SciPy-vendored HiGHS version is 1.8.0 and this
+        verifier must not pretend those enum semantics are our stable public schema.
+        """
+        if problem.has_integer_variables:
+            raise NotImplementedError("M3 vendored IIS verifier is limited to continuous LP")
+        core, h = self._rebuild(problem)
+        strategy = getattr(getattr(core, "IisStrategy", None), "kIisStrategyFromLpRowPriority", None)
+        if strategy is not None:
+            status = h.setOptionValue("iis_strategy", int(strategy))
+            if not _ok(core, status):
+                raise RuntimeError(f"HiGHS IIS strategy configuration failed: {status}")
+        h.run()
+        if h.getModelStatus() != core.HighsModelStatus.kInfeasible:
+            raise ValueError("IIS requested for a model not classified infeasible by HiGHS")
+        iis = core.HighsIis()
+        status = h.getIis(iis)
+        if not _ok(core, status):
+            raise RuntimeError(f"HiGHS getIis failed: {status}")
+        return HighsDevIISResult(
+            valid=bool(iis.valid),
+            row_indices=tuple(int(x) for x in iis.row_index),
+            row_bound_statuses=tuple(int(x) for x in iis.row_bound),
+            col_indices=tuple(int(x) for x in iis.col_index),
+            col_bound_statuses=tuple(int(x) for x in iis.col_bound),
+            strategy=int(iis.strategy),
+        )

solverpilot/benchmark/__init__.py

@@ -0,0 +1,23 @@
+from .acquire import acquire_dataset, dataset_spec_fingerprint, sha256_file
+from .baselines import BaselineFit, fit_sbs_backend, fit_sbs_backend_from_split, fixed_backend_policy, seeded_random_policy, threshold_policy
+from .bundle import create_result_bundle
+from .campaign import CAMPAIGN_SCHEMA_VERSION, CampaignSpec, CampaignValidation, load_campaign_spec, miplib2017_campaign_template, qplib_campaign_template, run_campaign, save_campaign_spec, validate_campaign
+from .environment import capture_environment, write_environment
+from .model import AcquisitionFile, AcquisitionRecord, DatasetSpec, RunSpec
+from .policy import evaluate_policy_jsonl, evaluate_policy_map, load_policy_map
+from .registry import benchmark_registry
+from .report import compute_scientific_metrics, render_scientific_report_markdown, scientific_report_payload, write_scientific_report
+from .runner import run_benchmark
+from .slurm import render_slurm_array, write_slurm_array
+from .splits import SplitRecord, SplitValidation, filter_rows_by_split, generate_group_split, instances_by_split, load_split_records, save_split_records, validate_split_file, validate_split_records
+from .specs import BUILTIN_DATASETS, MIPLIB2017_BENCHMARK_V2, QPLIB_ARCHIVE, get_builtin_dataset, load_dataset_spec, save_dataset_spec
+from .summary import load_rows, summarize_jsonl, summarize_rows
+from .verify import DatasetVerification, verify_acquired_dataset
+
+__all__ = [
+    "AcquisitionFile","AcquisitionRecord","DatasetSpec","RunSpec","BUILTIN_DATASETS","MIPLIB2017_BENCHMARK_V2","QPLIB_ARCHIVE","get_builtin_dataset","load_dataset_spec","save_dataset_spec","acquire_dataset","dataset_spec_fingerprint","sha256_file",
+    "capture_environment","write_environment","run_benchmark","benchmark_registry","summarize_jsonl","summarize_rows","load_rows","render_slurm_array","write_slurm_array","create_result_bundle","DatasetVerification","verify_acquired_dataset",
+    "load_policy_map","evaluate_policy_map","evaluate_policy_jsonl","SplitRecord","SplitValidation","filter_rows_by_split","generate_group_split","instances_by_split","load_split_records","save_split_records","validate_split_file","validate_split_records",
+    "CAMPAIGN_SCHEMA_VERSION","CampaignSpec","CampaignValidation","load_campaign_spec","miplib2017_campaign_template","qplib_campaign_template","run_campaign","save_campaign_spec","validate_campaign",
+    "BaselineFit","fit_sbs_backend","fit_sbs_backend_from_split","fixed_backend_policy","seeded_random_policy","threshold_policy","compute_scientific_metrics","scientific_report_payload","render_scientific_report_markdown","write_scientific_report",
+]

solverpilot/benchmark/acquire.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path, PureWindowsPath
+import shutil
+import tarfile
+import tempfile
+import time
+import urllib.request
+from urllib.parse import urlparse
+import zipfile
+
+from .model import AcquisitionFile, AcquisitionRecord, DatasetSpec
+
+
+
+def dataset_spec_fingerprint(spec: DatasetSpec) -> str:
+    payload = asdict(spec)
+    payload["instance_suffixes"] = list(spec.instance_suffixes)
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def sha256_file(path: str | Path, *, chunk_size: int = 1024 * 1024) -> str:
+    h = hashlib.sha256()
+    with Path(path).open("rb") as f:
+        while True:
+            chunk = f.read(chunk_size)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _download(url: str, dest: Path, *, timeout_s: float = 60.0, retries: int = 3) -> None:
+    if retries < 1:
+        raise ValueError("retries must be >= 1")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + ".part")
+    last_error: Exception | None = None
+    for attempt in range(retries):
+        offset = tmp.stat().st_size if tmp.exists() else 0
+        headers = {"User-Agent": "solverpilot-benchmark/0.1"}
+        if offset:
+            headers["Range"] = f"bytes={offset}-"
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as response:
+                status = getattr(response, "status", None)
+                append = bool(offset and status == 206)
+                mode = "ab" if append else "wb"
+                with tmp.open(mode) as out:
+                    shutil.copyfileobj(response, out, length=1024 * 1024)
+                    out.flush()
+                    os.fsync(out.fileno())
+            os.replace(tmp, dest)
+            return
+        except Exception as exc:
+            last_error = exc
+            if attempt + 1 < retries:
+                time.sleep(min(4.0, 0.5 * (2**attempt)))
+    if last_error is None:
+        raise RuntimeError("download failed without a captured exception")
+    raise last_error
+
+
+def _safe_member_path(root: Path, member_name: str) -> Path:
+    candidate = (root / member_name).resolve()
+    root_resolved = root.resolve()
+    if candidate != root_resolved and root_resolved not in candidate.parents:
+        raise ValueError(f"archive member escapes target directory: {member_name!r}")
+    return candidate
+
+
+def _extract_archive(archive: Path, target: Path) -> int:
+    """Extract an archive into a fresh directory and replace *target* only on success.
+
+    Extracting directly into an existing directory can leave stale files behind when
+    an upstream snapshot removes entries.  That is unacceptable for a benchmark
+    corpus because a later run could silently mix two dataset snapshots.
+    """
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f".{target.name}.extract-", dir=target.parent))
+    try:
+        count = 0
+        if zipfile.is_zipfile(archive):
+            with zipfile.ZipFile(archive) as zf:
+                for info in zf.infolist():
+                    _safe_member_path(staging, info.filename)
+                zf.extractall(staging)
+                count = sum(not x.is_dir() for x in zf.infolist())
+        elif tarfile.is_tarfile(archive):
+            with tarfile.open(archive) as tf:
+                members = tf.getmembers()
+                for member in members:
+                    _safe_member_path(staging, member.name)
+                    if member.issym() or member.islnk():
+                        raise ValueError("archive symlinks/hardlinks are not accepted")
+                tf.extractall(staging, filter="data")
+                count = sum(m.isfile() for m in members)
+        else:
+            raise ValueError(f"unsupported archive format: {archive}")
+
+        if target.exists():
+            shutil.rmtree(target)
+        os.replace(staging, target)
+        return count
+    except Exception:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+
+
+def _fetch_role(
+    *, role: str, url: str | None, filename: str | None, expected_sha256: str | None, target: Path,
+    timeout_s: float, retries: int, force: bool,
+) -> AcquisitionFile | None:
+    if url is None:
+        return None
+    name = filename or Path(urlparse(url).path).name
+    if not name:
+        raise ValueError(f"cannot derive filename from URL for {role}")
+    if (name in {".", ".."} or "/" in name or "\\" in name or ":" in name
+            or PureWindowsPath(name).is_absolute()):
+        raise ValueError(f"download filename must be a single local filename: {name!r}")
+    dest = target / name
+    _safe_member_path(target, name)
+    _safe_member_path(target, name + ".part")
+    if force or not dest.exists():
+        _download(url, dest, timeout_s=timeout_s, retries=retries)
+    digest = sha256_file(dest)
+    verified = expected_sha256 is not None and digest.lower() == expected_sha256.lower()
+    if expected_sha256 is not None and not verified:
+        raise ValueError(f"SHA-256 mismatch for {role}: expected {expected_sha256}, got {digest}")
+    return AcquisitionFile(
+        role=role,
+        url=url,
+        path=str(dest.resolve()),
+        size_bytes=dest.stat().st_size,
+        sha256=digest,
+        expected_sha256=expected_sha256,
+        verified=verified,
+    )
+
+
+def acquire_dataset(
+    spec: DatasetSpec,
+    target_dir: str | Path,
+    *,
+    extract: bool = True,
+    timeout_s: float = 60.0,
+    retries: int = 3,
+    force: bool = False,
+) -> AcquisitionRecord:
+    target = Path(target_dir)
+    target.mkdir(parents=True, exist_ok=True)
+    files = []
+    for role, url, filename, expected in (
+        ("archive", spec.archive_url, spec.archive_filename, spec.archive_sha256),
+        ("manifest", spec.manifest_url, spec.manifest_filename, spec.manifest_sha256),
+        ("reference", spec.reference_url, spec.reference_filename, spec.reference_sha256),
+    ):
+        item = _fetch_role(
+            role=role, url=url, filename=filename, expected_sha256=expected,
+            target=target, timeout_s=timeout_s, retries=retries, force=force,
+        )
+        if item is not None:
+            files.append(item)
+    extracted_count = 0
+    if extract:
+        archive_file = next((f for f in files if f.role == "archive"), None)
+        if archive_file is not None:
+            extracted_count = _extract_archive(Path(archive_file.path), target / "instances")
+    remote_roles = tuple(f.role for f in files)
+    unpinned_roles = tuple(sorted(f.role for f in files if f.expected_sha256 is None))
+    record = AcquisitionRecord(
+        dataset=spec.name,
+        spec_kind=spec.kind,
+        target_dir=str(target.resolve()),
+        files=tuple(files),
+        extracted=bool(extract and any(f.role == "archive" for f in files)),
+        extracted_files=extracted_count,
+        metadata=dict(spec.metadata),
+        schema_version="2.0",
+        spec_fingerprint=dataset_spec_fingerprint(spec),
+        provenance_level=spec.provenance_level,
+        all_remote_inputs_pinned=bool(remote_roles) and not unpinned_roles,
+        unpinned_roles=unpinned_roles,
+    )
+    lock = target / "acquisition-lock.json"
+    lock.write_text(json.dumps(asdict(record), indent=2, sort_keys=True), encoding="utf-8")
+    lock_digest = sha256_file(lock)
+    (target / "acquisition-lock.sha256").write_text(
+        f"{lock_digest}  {lock.name}\n", encoding="utf-8"
+    )
+    return record

solverpilot/benchmark/baselines.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import random
+from typing import Iterable, Mapping
+
+from .summary import summarize_rows
+
+
+@dataclass(frozen=True, slots=True)
+class BaselineFit:
+    baseline_type: str
+    selected_backend: str | None
+    training_instances_sha256: str
+    parameters: Mapping[str, object]
+
+
+def _instance_digest(instances: Iterable[str]) -> str:
+    canonical = "\n".join(sorted(map(str, instances))).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _entry(backend: str, overhead_s: float, *, component: str) -> dict:
+    overhead=float(overhead_s)
+    if overhead < 0: raise ValueError("overhead_s must be non-negative")
+    return {"backend":str(backend),"overhead_s":overhead,"overhead_components_s":{component:overhead}}
+
+
+def fixed_backend_policy(instances: Iterable[str], backend: str, *, overhead_s: float = 0.0) -> dict[str, dict]:
+    return {str(instance):_entry(backend,overhead_s,component="fixed_policy") for instance in sorted(set(instances))}
+
+
+def seeded_random_policy(instances: Iterable[str], backends: Iterable[str], *, seed: int, overhead_s: float = 0.0) -> dict[str, dict]:
+    choices=tuple(sorted(set(map(str,backends))))
+    if not choices: raise ValueError("backends must not be empty")
+    out={}
+    for instance in sorted(set(map(str,instances))):
+        local_seed=int.from_bytes(hashlib.sha256(f"{seed}\0{instance}".encode()).digest()[:8],"big")
+        out[instance]=_entry(random.Random(local_seed).choice(choices),overhead_s,component="random_selection")
+    return out
+
+
+def threshold_policy(features: Mapping[str, Mapping[str, float]], *, feature: str, threshold: float, le_backend: str, gt_backend: str, overhead_s: float) -> dict[str, dict]:
+    out={}
+    for instance in sorted(features):
+        row=features[instance]
+        if feature not in row: raise ValueError(f"feature {feature!r} missing for instance {instance!r}")
+        value=float(row[feature]); backend=le_backend if value <= threshold else gt_backend
+        entry=_entry(backend,overhead_s,component="rule_selection"); entry["rule"]={"feature":feature,"threshold":float(threshold),"value":value}; out[instance]=entry
+    return out
+
+
+def fit_sbs_backend(rows: list[dict], *, training_instances: Iterable[str], cutoff_s: float, par_penalty: float = 10.0, cost_field: str = "wall_s") -> BaselineFit:
+    train=tuple(sorted(set(map(str,training_instances))))
+    if not train: raise ValueError("training_instances must not be empty")
+    train_set=set(train); filtered=[r for r in rows if str(r.get("instance")) in train_set and r.get("backend") != "@auto"]
+    if not filtered: raise ValueError("no benchmark rows match training_instances")
+    summary=summarize_rows(filtered,cutoff_s=cutoff_s,par_penalty=par_penalty,cost_field=cost_field,bootstrap_draws=100,bootstrap_seed=0)
+    return BaselineFit("sbs-on-training-split",str(summary["sbs_solver"]),_instance_digest(train),{"cutoff_s":float(cutoff_s),"par_penalty":float(par_penalty),"cost_field":cost_field,"training_instances":len(train)})
+
+
+def fit_sbs_backend_from_split(rows: list[dict], split_records, *, fit_splits: tuple[str, ...] = ("train",), cutoff_s: float, par_penalty: float = 10.0, cost_field: str = "wall_s") -> BaselineFit:
+    normalized=tuple(str(x).lower() for x in fit_splits)
+    if "test" in normalized: raise ValueError("held-out test split must not be used to fit an SBS baseline")
+    from .splits import filter_rows_by_split, instances_by_split
+    filtered=filter_rows_by_split(rows,split_records,allowed_splits=normalized); grouped=instances_by_split(split_records)
+    training=[]
+    for name in normalized: training.extend(grouped[name])
+    return fit_sbs_backend(filtered,training_instances=training,cutoff_s=cutoff_s,par_penalty=par_penalty,cost_field=cost_field)