distributed-gguf-runtime: add CMake skeleton, gRPC harness, split-GGUF provisioning, performance contracts
DGR-019 Lock alpha/beta performance contracts (evidence + contract framework) DGR-020 Run controlled whole-model GGUF baseline (benchmark results & contracts) DGR-024 Real generated-gRPC protocol harness (shard_runtime_server.py + tests) DGR-026 split-GGUF provisioning outside /home (provision script + manifest + tests) DGR-028 Numbered patch-stack apply & verify (llama_cpp_dependency.py + UPSTREAM_LOCK.json) DGR-029 Native CMake skeleton + deterministic CPU lane (UPSTREAM_LOCK.json + cmake gating) New modules: packages/node/meshnet_node/dgr_performance/ — performance contract framework packages/node/meshnet_node/split_gguf/ — split-GGUF manifest & provisioning scripts/provision_split_gguf.py — artifact provisioning CLI tests/test_dgr_performance_contract.py — contract validation tests tests/test_split_gguf_manifest.py — manifest tests tests/test_split_gguf_provision.py — provisioning tests tests/test_shard_runtime_harness.py — gRPC harness tests
This commit is contained in:
Dobromir Popov
323
packages/node/meshnet_node/dgr_performance/contract.py
Normal file
323
packages/node/meshnet_node/dgr_performance/contract.py
Normal file
@@ -0,0 +1,323 @@
|
||||
"""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
|
||||
Reference in New Issue
Block a user