"""Quiet-host calibration records: the only way a scale-lane row becomes claimable.

A scale row's ``claim_eligible`` and ``evidence_class`` are DERIVED, never a

free flag: they are "calibrated_quiet_host"/true only when the run was given

a calibration record that validates here (content digest, schema, the same

runner, a quiet host, a clean identical-binary A/A campaign) AND the row's

own host-load sample is quiet. Every calibrated row embeds the full record

and its digest, so publish_gate re-validates each row from the row alone; a

JSONL hand-edited to ``claim_eligible: true`` (or to the calibrated evidence

class without a valid embedded record) is refused.

Record (JSON)::

    {"schema_version": 1, "kind": "oakbench_quiet_host_calibration",

     "runner_id": "...", "created_utc": "...", "calibration_bench_id": "...",

     "cpu_count": 12, "loadavg_per_core_max": 0.08,

     "aa_cells": 42, "aa_floor_median_pct": 4.1, "aa_false_claims": 0,

     "record_sha256": "<sha256 of the canonical JSON without this key>"}

"""

from __future__ import annotations

import hashlib

import json

from typing import Any, Dict, List, Optional, Tuple

SCHEMA_VERSION = 1

KIND = "oakbench_quiet_host_calibration"

CALIBRATED_EVIDENCE_CLASS = "calibrated_quiet_host"

DEVELOPMENT_EVIDENCE_CLASS = "development_only_loaded_host"

# Quiet-host thresholds (policy; change with a version bump).

POLICY_VERSION = "2026-09-29.1"

MAX_LOAD_PER_CORE = 0.25

MIN_AA_CELLS = 20

MAX_AA_FLOOR_MEDIAN_PCT = 10.0

REQUIRED = ("runner_id", "created_utc", "calibration_bench_id", "cpu_count", "loadavg_per_core_max", "aa_cells",

            "aa_floor_median_pct", "aa_false_claims")

def record_digest(record: Dict[str, Any]) -> str:

    body = {key: value for key, value in record.items() if key != "record_sha256"}

    return hashlib.sha256(json.dumps(body, sort_keys=True, separators=(",", ":")).encode()).hexdigest()

def seal(record: Dict[str, Any]) -> Dict[str, Any]:

    sealed = dict(record)

    sealed.update(schema_version=SCHEMA_VERSION, kind=KIND, policy_version=POLICY_VERSION)

    sealed["record_sha256"] = record_digest(sealed)

    return sealed

def validate(record: Any, runner_id: Optional[str]) -> List[str]:

    """Reasons the record does NOT make rows claimable ([] = valid)."""

    if not isinstance(record, dict):

        return ["calibration record missing or not an object"]

    reasons = []

    if record.get("schema_version") != SCHEMA_VERSION or record.get("kind") != KIND:

        reasons.append("wrong schema_version/kind")

    missing = [key for key in REQUIRED if key not in record]

    if missing:

        reasons.append(f"missing fields {missing}")

        return reasons

    if record.get("record_sha256") != record_digest(record):

        reasons.append("record_sha256 does not match content (edited record)")

    if runner_id is None or record.get("runner_id") != runner_id:

        reasons.append("calibration was taken on a different runner")

    load = record.get("loadavg_per_core_max")

    if not isinstance(load, (int, float)) or load > MAX_LOAD_PER_CORE:

        reasons.append(f"host not quiet: load/core {load} > {MAX_LOAD_PER_CORE}")

    cells = record.get("aa_cells")

    if not isinstance(cells, int) or cells < MIN_AA_CELLS:

        reasons.append(f"too few A/A cells ({cells} < {MIN_AA_CELLS})")

    floor = record.get("aa_floor_median_pct")

    if not isinstance(floor, (int, float)) or floor > MAX_AA_FLOOR_MEDIAN_PCT:

        reasons.append(f"A/A floor median {floor}% > {MAX_AA_FLOOR_MEDIAN_PCT}%")

    if record.get("aa_false_claims") != 0:

        reasons.append("identical-binary A/A produced claims")

    return reasons

def row_load_per_core(row: Dict[str, Any], cpu_count: Any) -> Optional[float]:

    sample = row.get("environment_sample") or {}

    load = sample.get("loadavg") if isinstance(sample, dict) else None

    if not isinstance(load, list) or not load or not isinstance(cpu_count, int) or cpu_count <= 0:

        return None

    return float(load[0]) / cpu_count

def derive(row: Dict[str, Any], record: Optional[Dict[str, Any]]) -> Tuple[str, bool, List[str]]:

    """(evidence_class, claim_eligible, reasons) for one row."""

    reasons = validate(record, row.get("runner_id")) if record is not None else ["no calibration record"]

    if not reasons:

        per_core = row_load_per_core(row, record.get("cpu_count"))

        if per_core is None or per_core > MAX_LOAD_PER_CORE:

            reasons.append(f"row host load/core {per_core} not quiet")

    if row.get("returncode") != 0:

        reasons.append("row is not a successful measurement")

    if reasons:

        return DEVELOPMENT_EVIDENCE_CLASS, False, reasons

    return CALIBRATED_EVIDENCE_CLASS, True, []

def stamp(row: Dict[str, Any], record: Optional[Dict[str, Any]]) -> Dict[str, Any]:

    evidence, eligible, reasons = derive(row, record)

    row["evidence_class"] = evidence

    row["claim_eligible"] = eligible

    row["claim_ineligible_reasons"] = reasons

    if eligible:

        row["calibration_record"] = record

        row["calibration_record_sha256"] = record["record_sha256"]

    return row

def gate_row(row: Dict[str, Any]) -> List[str]:

    """publish_gate: why a scale row may NOT be published ([] = publishable)."""

    if row.get("evidence_class") != CALIBRATED_EVIDENCE_CLASS:

        return [f"evidence_class {row.get('evidence_class')!r} is not {CALIBRATED_EVIDENCE_CLASS!r}"]

    record = row.get("calibration_record")

    if row.get("calibration_record_sha256") != (record or {}).get("record_sha256"):

        return ["calibration_record_sha256 does not match the embedded record"]

    evidence, eligible, reasons = derive(row, record)

    if not eligible or row.get("claim_eligible") is not True:

        return reasons or ["claim_eligible is not derived true"]

    return []