solverpilot 0.1__py3-none-any.whl

solverpilot/benchmark/bundle.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+import zipfile
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def create_result_bundle(
+    output_zip: str | Path,
+    *,
+    files: list[str | Path],
+    metadata: dict | None = None,
+) -> dict:
+    output = Path(output_zip)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    entries = []
+    seen_names = set()
+    with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for raw in files:
+            p = Path(raw)
+            if not p.is_file():
+                raise FileNotFoundError(p)
+            arcname = p.name
+            if arcname in seen_names:
+                raise ValueError(f"duplicate bundle filename: {arcname}")
+            seen_names.add(arcname)
+            data = p.read_bytes()
+            zf.writestr(arcname, data)
+            entries.append({"name": arcname, "size_bytes": len(data), "sha256": sha256_bytes(data)})
+        manifest = {"schema_version": "1.0", "metadata": metadata or {}, "entries": entries}
+        zf.writestr("bundle-manifest.json", json.dumps(manifest, indent=2, sort_keys=True).encode())
+    return {"path": str(output), "sha256": hashlib.sha256(output.read_bytes()).hexdigest(), "entries": entries}

solverpilot/benchmark/campaign.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import hashlib
+import json
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from solverpilot.evaluation import parse_test_manifest
+from .acquire import dataset_spec_fingerprint, sha256_file
+from .model import RunSpec
+from .runner import run_benchmark
+from .specs import MIPLIB2017_BENCHMARK_V2, QPLIB_ARCHIVE
+from .splits import validate_split_file
+from .verify import verify_acquired_dataset
+
+CAMPAIGN_SCHEMA_VERSION = "solverpilot.benchmark-campaign.v1"
+_DEFAULT_METRICS = ("par2","par10","solved_count","timeout_rate","optimality_gap","regret","selection_overhead")
+_ALLOWED_COST_FIELDS = {"wall_s","worker_solve_wall_s","trace.solve_s","trace.total_s"}
+
+
+def _freeze_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]:
+    out={}
+    for key,item in value.items():
+        if isinstance(item,Mapping): out[str(key)]=_freeze_mapping(item)
+        elif isinstance(item,list): out[str(key)]=tuple(item)
+        else: out[str(key)]=item
+    return MappingProxyType(out)
+
+def _canonical_sha256(payload: Mapping[str, Any]) -> str:
+    return hashlib.sha256(json.dumps(payload,sort_keys=True,separators=(",",":"),default=str).encode()).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignSpec:
+    campaign_id: str
+    dataset_name: str
+    dataset_spec_sha256: str
+    backends: tuple[str, ...]
+    repetitions: int = 1
+    cutoff_s: float = 600.0
+    hard_timeout_s: float | None = None
+    objective_atol: float = 1e-6
+    objective_rtol: float = 1e-7
+    seed: int = 0
+    thread_env_limit: int | None = 1
+    solver_threads: int | None = 1
+    worker_python_mode: str = "no_site"
+    cost_field: str = "wall_s"
+    metrics: tuple[str, ...] = _DEFAULT_METRICS
+    split_sha256: str | None = None
+    require_scientific_provenance: bool = True
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    schema_version: str = CAMPAIGN_SCHEMA_VERSION
+
+    def __post_init__(self):
+        if self.schema_version != CAMPAIGN_SCHEMA_VERSION: raise ValueError(f"unsupported campaign schema: {self.schema_version!r}")
+        if not self.campaign_id.strip() or not self.dataset_name.strip(): raise ValueError("campaign_id/dataset_name must be non-empty")
+        if len(self.dataset_spec_sha256)!=64 or any(c not in "0123456789abcdefABCDEF" for c in self.dataset_spec_sha256): raise ValueError("dataset_spec_sha256 must be a SHA-256 digest")
+        if self.split_sha256 is not None and (len(self.split_sha256)!=64 or any(c not in "0123456789abcdefABCDEF" for c in self.split_sha256)): raise ValueError("split_sha256 must be a SHA-256 digest")
+        if not self.backends or len(set(self.backends)) != len(self.backends): raise ValueError("backends must be non-empty and unique")
+        if self.repetitions < 1: raise ValueError("repetitions must be >= 1")
+        if self.cutoff_s <= 0: raise ValueError("cutoff_s must be positive")
+        if self.hard_timeout_s is not None and self.hard_timeout_s < self.cutoff_s: raise ValueError("hard_timeout_s must be >= cutoff_s when provided")
+        if self.thread_env_limit is not None and self.thread_env_limit < 1: raise ValueError("thread_env_limit must be >= 1")
+        if self.solver_threads is not None and self.solver_threads < 1: raise ValueError("solver_threads must be >= 1")
+        if self.worker_python_mode not in {"normal","no_site"}: raise ValueError("worker_python_mode must be 'normal' or 'no_site'")
+        if self.cost_field not in _ALLOWED_COST_FIELDS: raise ValueError(f"unsupported campaign cost_field: {self.cost_field!r}")
+        object.__setattr__(self,"backends",tuple(map(str,self.backends))); object.__setattr__(self,"metrics",tuple(map(str,self.metrics))); object.__setattr__(self,"metadata",_freeze_mapping(dict(self.metadata)))
+
+    def to_dict(self) -> dict[str,Any]:
+        def thaw(v):
+            if isinstance(v,Mapping): return {str(k):thaw(x) for k,x in v.items()}
+            if isinstance(v,tuple): return [thaw(x) for x in v]
+            return v
+        return {"campaign_id":self.campaign_id,"dataset_name":self.dataset_name,"dataset_spec_sha256":self.dataset_spec_sha256,"backends":list(self.backends),"repetitions":self.repetitions,"cutoff_s":self.cutoff_s,"hard_timeout_s":self.hard_timeout_s,"objective_atol":self.objective_atol,"objective_rtol":self.objective_rtol,"seed":self.seed,"thread_env_limit":self.thread_env_limit,"solver_threads":self.solver_threads,"worker_python_mode":self.worker_python_mode,"cost_field":self.cost_field,"metrics":list(self.metrics),"split_sha256":self.split_sha256,"require_scientific_provenance":self.require_scientific_provenance,"metadata":thaw(self.metadata),"schema_version":self.schema_version}
+    @property
+    def sha256(self): return _canonical_sha256(self.to_dict())
+
+
+@dataclass(frozen=True, slots=True)
+class CampaignValidation:
+    ok: bool
+    campaign_sha256: str
+    scientific_provenance_verified: bool | None
+    split_verified: bool | None
+    errors: tuple[str,...]=()
+    warnings: tuple[str,...]=()
+    def to_dict(self): return asdict(self)
+
+
+def save_campaign_spec(spec: CampaignSpec,path:str|Path)->None: Path(path).write_text(json.dumps(spec.to_dict(),indent=2,sort_keys=True),encoding="utf-8")
+def load_campaign_spec(path:str|Path)->CampaignSpec:
+    p=json.loads(Path(path).read_text(encoding="utf-8")); p["backends"]=tuple(p.get("backends",())); p["metrics"]=tuple(p.get("metrics",_DEFAULT_METRICS)); return CampaignSpec(**p)
+
+def miplib2017_campaign_template(backends: tuple[str,...], *, repetitions:int=1, cutoff_s:float=3600.0, hard_timeout_s:float|None=None, seed:int=0, solver_threads:int|None=1)->CampaignSpec:
+    return CampaignSpec(campaign_id="miplib2017-benchmark-v2",dataset_name=MIPLIB2017_BENCHMARK_V2.name,dataset_spec_sha256=dataset_spec_fingerprint(MIPLIB2017_BENCHMARK_V2),backends=backends,repetitions=repetitions,cutoff_s=cutoff_s,hard_timeout_s=hard_timeout_s,seed=seed,solver_threads=solver_threads,require_scientific_provenance=True,metadata={"benchmark_instances":240,"benchmark_version":2,"reference_solution_version":36,"reference_solution_release":"2026-01-26","official_source":"https://miplib.zib.de/download.html","status":"protocol-ready; execution requires fully pinned official inputs"})
+
+def qplib_campaign_template(backends: tuple[str,...], *, cutoff_s:float=3600.0, seed:int=0)->CampaignSpec:
+    return CampaignSpec(campaign_id="qplib-supported-subset-v1",dataset_name=QPLIB_ARCHIVE.name,dataset_spec_sha256=dataset_spec_fingerprint(QPLIB_ARCHIVE),backends=backends,cutoff_s=cutoff_s,seed=seed,require_scientific_provenance=True,metadata={"official_continuous_instances":134,"official_discrete_instances":319,"supported_subset_count":None,"execution_supported":False,"blocked_on":"strict QPLIB parser/filter and pinned supported-subset manifest/reference","official_source":"https://qplib.zib.de/"})
+
+def _lock_payload(target:Path):
+    lock=target/"acquisition-lock.json"
+    if not lock.exists(): raise FileNotFoundError(lock)
+    return json.loads(lock.read_text(encoding="utf-8"))
+def _role_path(lock:Mapping[str,Any],role:str)->Path|None:
+    for item in lock.get("files",[]):
+        if isinstance(item,Mapping) and item.get("role")==role: return Path(str(item["path"]))
+    return None
+
+def validate_campaign(spec:CampaignSpec, *, dataset_target:str|Path|None=None, split_path:str|Path|None=None)->CampaignValidation:
+    errors=[]; warnings=[]; scientific=None; split_verified=None; expected_split_instances=None
+    if dataset_target is not None:
+        target=Path(dataset_target); report=verify_acquired_dataset(target); scientific=report.scientific_provenance_verified; lock=_lock_payload(target)
+        if str(lock.get("dataset"))!=spec.dataset_name: errors.append("campaign dataset_name does not match acquisition lock")
+        if str(lock.get("spec_fingerprint"))!=spec.dataset_spec_sha256: errors.append("campaign dataset_spec_sha256 does not match acquisition lock")
+        if not report.ok: errors.extend(report.errors)
+        if spec.require_scientific_provenance and not report.scientific_provenance_verified: errors.append("campaign requires scientifically verified provenance, but acquisition is not fully pinned")
+        if not report.scientific_provenance_verified: warnings.append("dataset integrity may be locally verified without authenticating the official snapshot")
+        manifest=_role_path(lock,"manifest")
+        if manifest is not None and manifest.exists():
+            names=parse_test_manifest(manifest.read_text(encoding="utf-8"))
+            def key(filename):
+                lower=filename.lower()
+                for suffix in (".mps.gz",".mps",".lp.gz",".lp"):
+                    if lower.endswith(suffix): return filename[:-len(suffix)]
+                return Path(filename).stem
+            expected_split_instances=tuple(key(n) for n in names)
+    if split_path is None and spec.split_sha256 is not None: errors.append("campaign binds split_sha256 but no split_path was supplied")
+    if split_path is not None:
+        path=Path(split_path); digest=sha256_file(path)
+        if spec.split_sha256 is not None and digest.lower()!=spec.split_sha256.lower(): errors.append("split artifact SHA-256 does not match campaign")
+        sr=validate_split_file(path,expected_instances=expected_split_instances); split_verified=sr.ok
+        if not sr.ok: errors.extend(sr.errors)
+    return CampaignValidation(not errors,spec.sha256,scientific,split_verified,tuple(errors),tuple(warnings))
+
+def run_campaign(spec:CampaignSpec, *, dataset_target:str|Path, output_jsonl:str|Path, split_path:str|Path|None=None, allow_unverified_dataset:bool=False, registry=None)->dict[str,Any]:
+    validation=validate_campaign(spec,dataset_target=dataset_target,split_path=split_path)
+    if not validation.ok:
+        if not allow_unverified_dataset: raise ValueError("campaign validation failed: "+"; ".join(validation.errors))
+        remaining=[e for e in validation.errors if "scientifically verified provenance" not in e]
+        if remaining: raise ValueError("campaign validation failed: "+"; ".join(remaining))
+    target=Path(dataset_target); lock=_lock_payload(target); manifest=_role_path(lock,"manifest"); reference=_role_path(lock,"reference")
+    if manifest is None: raise ValueError("campaign dataset acquisition has no manifest")
+    if spec.require_scientific_provenance and reference is None: raise ValueError("scientific campaign requires a reference file")
+    rs=RunSpec(dataset_dir=target/"instances",manifest=manifest,reference=reference,backends=spec.backends,output_jsonl=Path(output_jsonl),repetitions=spec.repetitions,time_limit_s=spec.cutoff_s,hard_timeout_s=spec.hard_timeout_s,objective_atol=spec.objective_atol,objective_rtol=spec.objective_rtol,seed=spec.seed,thread_env_limit=spec.thread_env_limit,solver_threads=spec.solver_threads,worker_python_mode=spec.worker_python_mode)
+    summary=run_benchmark(rs,registry=registry); result_path=Path(output_jsonl)
+    sidecar={"schema_version":"solverpilot.campaign-run.v1","campaign_id":spec.campaign_id,"campaign_sha256":spec.sha256,"scientific_provenance_verified":bool(validation.scientific_provenance_verified),"allow_unverified_dataset":bool(allow_unverified_dataset),"deployable_scientific_evidence":bool(validation.scientific_provenance_verified and not allow_unverified_dataset),"result_jsonl":str(result_path),"result_jsonl_sha256":sha256_file(result_path),"run_summary":summary}
+    Path(str(result_path)+".campaign.json").write_text(json.dumps(sidecar,indent=2,sort_keys=True,default=str),encoding="utf-8"); return sidecar

solverpilot/benchmark/environment.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import platform
+import socket
+import sys
+from typing import Iterable
+
+
+_THREAD_ENV_KEYS = (
+    "OMP_NUM_THREADS",
+    "OPENBLAS_NUM_THREADS",
+    "MKL_NUM_THREADS",
+    "NUMEXPR_NUM_THREADS",
+    "VECLIB_MAXIMUM_THREADS",
+    "BLIS_NUM_THREADS",
+)
+
+
+def _cpu_model() -> str | None:
+    cpuinfo = Path("/proc/cpuinfo")
+    if cpuinfo.exists():
+        for line in cpuinfo.read_text(errors="ignore").splitlines():
+            if line.lower().startswith("model name") and ":" in line:
+                return line.split(":", 1)[1].strip()
+    return platform.processor() or None
+
+
+def _memory_bytes() -> int | None:
+    meminfo = Path("/proc/meminfo")
+    if meminfo.exists():
+        for line in meminfo.read_text(errors="ignore").splitlines():
+            if line.startswith("MemTotal:"):
+                parts = line.split()
+                if len(parts) >= 2:
+                    return int(parts[1]) * 1024
+    return None
+
+
+def thread_environment(limit: int | None) -> dict[str, str]:
+    """Return environment variables used to cap common C/BLAS thread pools.
+
+    This does not prove that a solver's own internal thread pool is controlled.
+    Backend-level thread control is represented separately by ``solver_threads`` in
+    the benchmark protocol.
+    """
+
+    if limit is None:
+        return {}
+    if limit < 1:
+        raise ValueError("thread environment limit must be >= 1")
+    value = str(int(limit))
+    return {key: value for key in _THREAD_ENV_KEYS}
+
+
+def capture_environment(*, packages: Iterable[str] = ()) -> dict:
+    versions: dict[str, str | None] = {}
+    for name in packages:
+        try:
+            versions[name] = importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            versions[name] = None
+    return {
+        "python": sys.version,
+        "python_executable": sys.executable,
+        "platform": platform.platform(),
+        "machine": platform.machine(),
+        "hostname": socket.gethostname(),
+        "cpu_model": _cpu_model(),
+        "logical_cpus": os.cpu_count(),
+        "memory_bytes": _memory_bytes(),
+        "packages": versions,
+        "env_threads": {key: os.environ.get(key) for key in _THREAD_ENV_KEYS},
+    }
+
+
+def benchmark_environment_fingerprint(
+    environment: dict,
+    *,
+    thread_env_limit: int | None,
+    solver_threads: int | None,
+    worker_python_mode: str = "no_site",
+) -> str:
+    """Hash timing-relevant execution environment fields, excluding hostname.
+
+    Hostname is deliberately excluded so homogeneous cluster nodes can merge. CPU,
+    platform, Python/package versions, and the declared thread policy are retained.
+    """
+
+    payload = {
+        "schema_version": "1.0",
+        "python": environment.get("python"),
+        "platform": environment.get("platform"),
+        "machine": environment.get("machine"),
+        "cpu_model": environment.get("cpu_model"),
+        "logical_cpus": environment.get("logical_cpus"),
+        "memory_bytes": environment.get("memory_bytes"),
+        "packages": environment.get("packages", {}),
+        "thread_env_limit": thread_env_limit,
+        "solver_threads": solver_threads,
+        "worker_python_mode": worker_python_mode,
+        "effective_thread_env": thread_environment(thread_env_limit),
+    }
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode()
+    return hashlib.sha256(raw).hexdigest()
+
+
+def write_environment(path: str | Path, *, packages: Iterable[str] = ()) -> dict:
+    payload = capture_environment(packages=packages)
+    Path(path).write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    return payload

solverpilot/benchmark/integrity.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+CURRENT_BENCHMARK_ROW_SCHEMA = "1.5"
+
+
+def canonical_sha256(value: Any) -> str:
+    raw = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def experiment_identity(*, protocol_id: str, environment_id: str, backend_set_sha256: str, thread_policy: Mapping[str, Any]) -> str:
+    return canonical_sha256({
+        "protocol_id": protocol_id,
+        "environment_id": environment_id,
+        "backend_set_sha256": backend_set_sha256,
+        "thread_policy": dict(thread_policy),
+    })
+
+
+def row_sha256(row: Mapping[str, Any]) -> str:
+    return canonical_sha256({str(k): v for k, v in row.items() if k != "row_sha256"})
+
+
+def attach_row_integrity(row: Mapping[str, Any]) -> dict[str, Any]:
+    payload = dict(row)
+    payload.pop("row_sha256", None)
+    payload["row_sha256"] = row_sha256(payload)
+    return payload
+
+
+def verify_row_integrity(row: Mapping[str, Any], *, context: str = "benchmark row") -> None:
+    schema = str(row.get("schema_version") or "")
+    recorded = row.get("row_sha256")
+    if recorded is None:
+        if schema == CURRENT_BENCHMARK_ROW_SCHEMA:
+            raise ValueError(f"{context}: schema {schema} row is missing row_sha256")
+        return
+    text = str(recorded)
+    if len(text) != 64 or any(ch not in "0123456789abcdefABCDEF" for ch in text):
+        raise ValueError(f"{context}: invalid row_sha256")
+    if row_sha256(row).lower() != text.lower():
+        raise ValueError(f"{context}: row_sha256 mismatch")

solverpilot/benchmark/model.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+
+_PROVENANCE_LEVELS = {
+    "UNSPECIFIED",
+    "VERIFIED_FROZEN",
+    "PINNED_EXTERNAL",
+    "PINNED_ARCHIVE_ONLY",
+    "UNPINNED_EXTERNAL",
+    "LOCAL_ONLY",
+}
+
+
+class _FrozenDict(dict):
+    """Immutable dict compatible with dataclasses.asdict/json workflows."""
+
+    def _blocked(self, *args, **kwargs):
+        raise TypeError("immutable mapping")
+
+    __setitem__ = __delitem__ = clear = pop = popitem = setdefault = update = _blocked
+
+    def __deepcopy__(self, memo):
+        return dict(self)
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return _FrozenDict({k: _freeze(v) for k, v in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze(v) for v in value)
+    if isinstance(value, tuple):
+        return tuple(_freeze(v) for v in value)
+    if isinstance(value, set):
+        return frozenset(_freeze(v) for v in value)
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class DatasetSpec:
+    name: str
+    kind: str
+    archive_url: str | None = None
+    manifest_url: str | None = None
+    reference_url: str | None = None
+    archive_sha256: str | None = None
+    manifest_sha256: str | None = None
+    reference_sha256: str | None = None
+    archive_filename: str | None = None
+    manifest_filename: str | None = None
+    reference_filename: str | None = None
+    instance_suffixes: tuple[str, ...] = (".mps.gz", ".mps")
+    provenance_level: str = "UNSPECIFIED"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        level = str(self.provenance_level).strip().upper()
+        if level not in _PROVENANCE_LEVELS:
+            raise ValueError(f"unsupported provenance_level: {self.provenance_level!r}")
+        object.__setattr__(self, "provenance_level", level)
+        object.__setattr__(self, "metadata", _freeze(dict(self.metadata)))
+        object.__setattr__(self, "instance_suffixes", tuple(self.instance_suffixes))
+
+
+@dataclass(frozen=True, slots=True)
+class RunSpec:
+    dataset_dir: Path
+    manifest: Path
+    reference: Path | None
+    backends: tuple[str, ...]
+    output_jsonl: Path
+    repetitions: int = 1
+    time_limit_s: float | None = None
+    hard_timeout_s: float | None = None
+    objective_atol: float = 1e-6
+    objective_rtol: float = 1e-7
+    shard_index: int = 0
+    shard_count: int = 1
+    resume: bool = True
+    seed: int = 0
+    thread_env_limit: int | None = 1
+    solver_threads: int | None = None
+    worker_python_mode: str = "no_site"
+
+    def __post_init__(self) -> None:
+        if self.repetitions < 1:
+            raise ValueError("repetitions must be >= 1")
+        if self.time_limit_s is not None and self.time_limit_s <= 0:
+            raise ValueError("time_limit_s must be positive")
+        if self.hard_timeout_s is not None and self.hard_timeout_s <= 0:
+            raise ValueError("hard_timeout_s must be positive")
+        if self.thread_env_limit is not None and self.thread_env_limit < 1:
+            raise ValueError("thread_env_limit must be >= 1")
+        if self.solver_threads is not None and self.solver_threads < 1:
+            raise ValueError("solver_threads must be >= 1")
+        if self.worker_python_mode not in {"normal", "no_site"}:
+            raise ValueError("worker_python_mode must be 'normal' or 'no_site'")
+        if not self.backends:
+            raise ValueError("backends must not be empty")
+        if self.shard_count < 1:
+            raise ValueError("shard_count must be >= 1")
+        if not 0 <= self.shard_index < self.shard_count:
+            raise ValueError("shard_index must be in [0, shard_count)")
+
+
+@dataclass(frozen=True, slots=True)
+class AcquisitionFile:
+    role: str
+    url: str
+    path: str
+    size_bytes: int
+    sha256: str
+    expected_sha256: str | None
+    verified: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AcquisitionRecord:
+    dataset: str
+    spec_kind: str
+    target_dir: str
+    files: tuple[AcquisitionFile, ...]
+    extracted: bool
+    extracted_files: int
+    metadata: Mapping[str, Any]
+    schema_version: str
+    spec_fingerprint: str
+    provenance_level: str
+    all_remote_inputs_pinned: bool
+    unpinned_roles: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not self.schema_version:
+            raise ValueError("schema_version must not be empty")
+        if len(self.spec_fingerprint) != 64 or any(ch not in "0123456789abcdefABCDEF" for ch in self.spec_fingerprint):
+            raise ValueError("spec_fingerprint must be a SHA-256 hex digest")
+        level = str(self.provenance_level).strip().upper()
+        if level not in _PROVENANCE_LEVELS:
+            raise ValueError(f"unsupported provenance_level: {self.provenance_level!r}")
+        object.__setattr__(self, "provenance_level", level)
+        object.__setattr__(self, "metadata", _freeze(dict(self.metadata)))
+        object.__setattr__(self, "files", tuple(self.files))
+        object.__setattr__(self, "unpinned_roles", tuple(sorted(set(self.unpinned_roles))))