neuron-tai/packages/node/meshnet_node/dgr_performance/contract.py

"""The locked DGR-019 alpha/beta performance contract.

Four benchmark lanes feed the DeepSeek V4 Flash release gates: controlled
safetensors, whole-model GGUF, dense distributed GGUF, and V4 Flash
distributed. The first two are already locked by DGR-001
(:mod:`meshnet_node.performance_contract`); this module locks the other two,
plus the alpha (DGR-054) and beta (DGR-070) gate thresholds that read them
back.

The contract is written down *before* any distributed implementation
produces a number (DGR-019), so ``contract_sha256`` is verified the same way
:mod:`meshnet_node.glm_alpha.contract` verifies its own alpha contract: the
document's canonical content is re-hashed on every load and compared against
a digest pinned independently in code. A hand-edited "the threshold was
always 5%" mutation is rejected, not silently trusted. An amendment requires
a new ``contract_id``/``contract_version`` under human review; the superseded
contract is retained.

Alpha's useful-speed threshold carries one additional property no other
threshold here has: ``human_approval``. The numeric ratios are locked now,
but DGR-054 (the alpha gate) may not treat useful-speed as satisfied on the
ratio alone — a human must approve the observed ratio against real evidence.
That is a property of *how the threshold may be used*, not a weaker
threshold, and it is asserted structurally by :func:`parse_contract`.
"""

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass
from importlib.resources import files
from pathlib import Path
from types import MappingProxyType
from typing import Any, Mapping

CONTRACT_SCHEMA_VERSION = 1
CONTRACT_VERSION = 1
CONTRACT_ID = "dgr-alpha-beta-performance/v1"
CONTRACT_V1_SHA256 = "cb5a482a8f142bf45b1dd401743d408acbfe5f85bab86023144a8c9485ac6379"

_CONTRACT_RESOURCE = "alpha-beta-contract-v1.json"

DIGEST_FIELD = "contract_sha256"

REQUIRED_LANES: tuple[str, ...] = (
    "controlled-safetensors",
    "whole-model-gguf",
    "dense-distributed-gguf",
    "v4-flash-distributed",
)

# Lanes DGR-019 locks directly; the other two are already locked by DGR-001
# (meshnet_node.performance_contract) and are referenced, not re-defined.
NEWLY_LOCKED_LANES: tuple[str, ...] = ("dense-distributed-gguf", "v4-flash-distributed")
REFERENCED_LANES: tuple[str, ...] = ("controlled-safetensors", "whole-model-gguf")

ALPHA_VERDICTS: tuple[str, ...] = ("alpha", "optimize", "stop")
BETA_VERDICTS: tuple[str, ...] = ("beta", "targeted-optimization", "stop-rollback")

REQUIRED_TOP_LEVEL_SECTIONS: tuple[str, ...] = (
    "prompt_set",
    "sampling",
    "lanes",
    "gain_attribution",
    "certification_scenarios",
    "alpha",
    "beta",
)


class DgrPerformanceContractError(ValueError):
    """Raised when the alpha/beta performance contract is missing, malformed, or mutated."""


def canonical_sha256(value: Any) -> str:
    """SHA-256 over canonical JSON — the repository's digest convention."""
    payload = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()


def contract_signing_payload(document: Mapping[str, Any]) -> dict:
    """The contract content the digest covers: everything except the digest itself."""
    unsigned = dict(document)
    unsigned.pop(DIGEST_FIELD, None)
    return unsigned


def compute_contract_digest(document: Mapping[str, Any]) -> str:
    return canonical_sha256(_thaw_json(contract_signing_payload(document)))


def _freeze_json(value: Any) -> Any:
    if isinstance(value, Mapping):
        return MappingProxyType({str(key): _freeze_json(item) for key, item in value.items()})
    if isinstance(value, list):
        return tuple(_freeze_json(item) for item in value)
    return value


def _thaw_json(value: Any) -> Any:
    if isinstance(value, Mapping):
        return {str(key): _thaw_json(item) for key, item in value.items()}
    if isinstance(value, tuple):
        return [_thaw_json(item) for item in value]
    return value


@dataclass(frozen=True)
class AlphaBetaContract:
    """A locked, digest-bound alpha/beta performance contract."""

    schema_version: int
    contract_version: int
    contract_id: str
    locked_at: str
    locked_by: str
    lanes: Mapping[str, Mapping[str, Any]]
    gain_attribution: Mapping[str, Any]
    certification_scenarios: Mapping[str, Any]
    alpha: Mapping[str, Any]
    beta: Mapping[str, Any]
    amendment_policy: str
    digest: str
    raw: Mapping[str, Any]
    source: str = "<memory>"

    def lane(self, name: str) -> Mapping[str, Any]:
        if name not in self.lanes:
            raise DgrPerformanceContractError(f"lane {name!r} is missing from {self.source}")
        return self.lanes[name]

    def to_dict(self) -> dict:
        return _thaw_json(self.raw)


def parse_contract(data: Any, source: str = "<memory>") -> AlphaBetaContract:
    """Validate a contract document and verify it has not been mutated since locking."""
    if not isinstance(data, Mapping):
        raise DgrPerformanceContractError(f"contract root in {source} must be a JSON object")

    schema_version = data.get("schema_version")
    if (
        not isinstance(schema_version, int)
        or isinstance(schema_version, bool)
        or schema_version != CONTRACT_SCHEMA_VERSION
    ):
        raise DgrPerformanceContractError(
            f"{source} declares contract schema version {schema_version!r}, but this node "
            f"reads version {CONTRACT_SCHEMA_VERSION}"
        )

    contract_version = data.get("contract_version")
    if (
        not isinstance(contract_version, int)
        or isinstance(contract_version, bool)
        or contract_version != CONTRACT_VERSION
    ):
        raise DgrPerformanceContractError(
            f"{source} declares contract version {contract_version!r}, but this node reads "
            f"version {CONTRACT_VERSION}"
        )

    contract_id = data.get("contract_id")
    if contract_id != CONTRACT_ID:
        raise DgrPerformanceContractError(
            f"{source} declares contract_id {contract_id!r}, but this node is locked to "
            f"{CONTRACT_ID!r}"
        )

    for field in ("locked_at", "locked_by"):
        value = data.get(field)
        if not isinstance(value, str) or not value.strip():
            raise DgrPerformanceContractError(f"{source} must carry a non-empty {field}")

    if not data.get("locked_before_target_execution"):
        raise DgrPerformanceContractError(
            f"{source} does not assert locked_before_target_execution; a contract written "
            "after the results are known is not a contract"
        )

    declared = data.get(DIGEST_FIELD)
    if not isinstance(declared, str) or not declared:
        raise DgrPerformanceContractError(
            f"{source} carries no {DIGEST_FIELD}; an unsealed contract cannot prove it "
            "predates the results it judges"
        )

    computed = compute_contract_digest(data)
    if computed != declared:
        raise DgrPerformanceContractError(
            f"{source} has been modified since it was locked: its content hashes to "
            f"{computed}, but it declares {declared}. Thresholds are locked before "
            "benchmark result ingestion and may not be weakened afterwards. To change them, "
            "open a new contract_id under human review; do not edit this one."
        )

    missing_sections = [
        name for name in REQUIRED_TOP_LEVEL_SECTIONS if not isinstance(data.get(name), Mapping)
    ]
    if missing_sections:
        raise DgrPerformanceContractError(
            f"{source} is missing locked section(s) {missing_sections}"
        )

    lanes = data["lanes"]
    missing_lanes = [name for name in REQUIRED_LANES if name not in lanes]
    if missing_lanes:
        raise DgrPerformanceContractError(f"{source} is missing lane(s) {missing_lanes}")
    for name in REFERENCED_LANES:
        if not lanes[name].get("locked_elsewhere"):
            raise DgrPerformanceContractError(
                f"{source} lane {name!r} must reference its existing DGR-001 lock, not "
                "re-define one"
            )
    for name in NEWLY_LOCKED_LANES:
        for required_field in ("prompt_ids", "hardware", "metrics", "certification_scenarios"):
            if required_field not in lanes[name]:
                raise DgrPerformanceContractError(
                    f"{source} lane {name!r} is missing {required_field!r}"
                )

    alpha = data["alpha"]
    alpha_verdicts = alpha.get("verdicts")
    if not isinstance(alpha_verdicts, list) or list(alpha_verdicts) != list(ALPHA_VERDICTS):
        raise DgrPerformanceContractError(
            f"{source} alpha.verdicts must be exactly {list(ALPHA_VERDICTS)}"
        )
    human_approval = alpha.get("useful_speed", {}).get("human_approval")
    if not isinstance(human_approval, Mapping) or human_approval.get("required") is not True:
        raise DgrPerformanceContractError(
            f"{source} alpha.useful_speed.human_approval.required must be true; alpha "
            "requires a human-approved useful-speed threshold, not an automatic one"
        )

    beta = data["beta"]
    beta_verdicts = beta.get("verdicts")
    if not isinstance(beta_verdicts, list) or list(beta_verdicts) != list(BETA_VERDICTS):
        raise DgrPerformanceContractError(
            f"{source} beta.verdicts must be exactly {list(BETA_VERDICTS)}"
        )
    missing_beta_axes = [
        axis for axis in ("concurrency", "long_context", "failure", "sustained_throughput")
        if axis not in beta
    ]
    if missing_beta_axes:
        raise DgrPerformanceContractError(
            f"{source} beta is missing axis/axes {missing_beta_axes}"
        )

    amendment_policy = data.get("amendment_policy")
    if not isinstance(amendment_policy, str) or not amendment_policy.strip():
        raise DgrPerformanceContractError(f"{source} must state its amendment policy")

    if declared != CONTRACT_V1_SHA256:
        raise DgrPerformanceContractError(
            f"{source} is a re-sealed mutation of {CONTRACT_ID}: digest {declared} does not "
            f"match the trusted pre-execution digest {CONTRACT_V1_SHA256}. An amendment "
            "requires a new supported contract identity under human review."
        )

    frozen = _freeze_json(data)

    return AlphaBetaContract(
        schema_version=schema_version,
        contract_version=contract_version,
        contract_id=contract_id,
        locked_at=str(data["locked_at"]),
        locked_by=str(data["locked_by"]),
        lanes=frozen["lanes"],
        gain_attribution=frozen["gain_attribution"],
        certification_scenarios=frozen["certification_scenarios"],
        alpha=frozen["alpha"],
        beta=frozen["beta"],
        amendment_policy=amendment_policy,
        digest=declared,
        raw=frozen,
        source=source,
    )


def load_contract(path: Path | None = None) -> AlphaBetaContract:
    """Load the packaged alpha/beta performance contract, or one at ``path``."""
    if path is not None:
        source = str(path)
        try:
            raw = path.read_text(encoding="utf-8")
        except OSError as exc:
            raise DgrPerformanceContractError(f"cannot read {source}: {exc.strerror or exc}") from exc
    else:
        source = f"packaged {_CONTRACT_RESOURCE}"
        try:
            raw = (
                files("meshnet_node.dgr_performance")
                .joinpath("data", _CONTRACT_RESOURCE)
                .read_text(encoding="utf-8")
            )
        except (OSError, FileNotFoundError, ModuleNotFoundError) as exc:
            raise DgrPerformanceContractError(
                f"{source} is missing from this node installation ({type(exc).__name__})"
            ) from exc

    try:
        data = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise DgrPerformanceContractError(
            f"{source} is not valid JSON: {exc.msg} at line {exc.lineno} column {exc.colno}"
        ) from exc

    return parse_contract(data, source=source)


def seal_contract(document: Mapping[str, Any]) -> dict:
    """Return the document with a freshly computed digest.

    This is the only supported way to produce a contract file. It is
    deliberately not called at load time: sealing on load would turn every
    mutation into a valid contract, which is precisely the property the
    digest exists to deny.
    """
    sealed = dict(document)
    sealed[DIGEST_FIELD] = compute_contract_digest(document)
    return sealed