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
2026-07-23 09:55:00 +03:00
parent 47bad0b7e1
commit 966aa10854
36 changed files with 7225 additions and 374 deletions
--- a/tests/test_dgr_performance_contract.py
+++ b/tests/test_dgr_performance_contract.py
@@ -0,0 +1,339 @@
+"""DGR-019 — the locked alpha/beta performance contract.
+
+Deterministic, offline, GPU-free, model-download-free. These tests assert
+against the *pinned* v1 contract, so they fail if a later change loosens a
+threshold, drops a lane, or removes the human-approval gate on alpha's
+useful-speed threshold without going through a new contract_id/version.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+import pytest
+
+from meshnet_node.dgr_performance import (
+    ALPHA_VERDICTS,
+    BETA_VERDICTS,
+    CONTRACT_ID,
+    CONTRACT_V1_SHA256,
+    NEWLY_LOCKED_LANES,
+    REFERENCED_LANES,
+    REQUIRED_LANES,
+    AlphaBetaContract,
+    DgrPerformanceContractError,
+    compute_contract_digest,
+    load_contract,
+    parse_contract,
+    seal_contract,
+)
+
+
+@pytest.fixture(scope="module")
+def contract() -> AlphaBetaContract:
+    return load_contract()
+
+
+@pytest.fixture
+def contract_doc(contract: AlphaBetaContract) -> dict:
+    return contract.to_dict()
+
+
+# --------------------------------------------------------------------------
+# Loading and identity
+# --------------------------------------------------------------------------
+
+
+def test_loads_the_packaged_contract(contract: AlphaBetaContract) -> None:
+    assert contract.contract_id == CONTRACT_ID == "dgr-alpha-beta-performance/v1"
+    assert contract.schema_version == 1
+    assert contract.contract_version == 1
+    assert contract.locked_by == "DGR-019"
+    assert contract.digest == CONTRACT_V1_SHA256
+
+
+def test_digest_matches_recomputation_from_content(contract_doc: dict) -> None:
+    assert compute_contract_digest(contract_doc) == CONTRACT_V1_SHA256
+
+
+def test_all_four_lanes_are_present(contract: AlphaBetaContract) -> None:
+    assert set(contract.lanes) == set(REQUIRED_LANES) == {
+        "controlled-safetensors",
+        "whole-model-gguf",
+        "dense-distributed-gguf",
+        "v4-flash-distributed",
+    }
+
+
+# --------------------------------------------------------------------------
+# Lanes 1 & 2 reference the existing DGR-001 lock; lanes 3 & 4 are new
+# --------------------------------------------------------------------------
+
+
+def test_controlled_and_whole_model_lanes_reference_the_existing_dgr_001_lock(
+    contract: AlphaBetaContract,
+) -> None:
+    for name in REFERENCED_LANES:
+        lane = contract.lane(name)
+        assert lane["locked_elsewhere"] is True
+        assert lane["contract_module"] == "meshnet_node.performance_contract"
+        assert lane["contract_id"] == "dgr-001-controlled-whole-model-baseline-v1"
+
+
+def test_dgr_001_referenced_contract_id_matches_the_real_locked_module() -> None:
+    from meshnet_node.performance_contract import ContractThresholds
+
+    # DGR-001's thresholds are immutable v1; this pins the assumption this
+    # contract's reference actually still points at, without re-locking them.
+    assert ContractThresholds().min_decode_speedup == 1.25
+    assert ContractThresholds().max_resident_memory_ratio == 0.75
+
+
+def test_dense_and_v4_lanes_are_newly_locked_with_full_benchmark_plans(
+    contract: AlphaBetaContract,
+) -> None:
+    for name in NEWLY_LOCKED_LANES:
+        lane = contract.lane(name)
+        assert "locked_elsewhere" not in lane
+        assert lane["prompt_ids"]
+        assert lane["hardware"]
+        assert lane["metrics"]
+        assert lane["certification_scenarios"]["stage_count"]
+        assert lane["certification_scenarios"]["quantization"]
+
+
+def test_dense_lane_defines_fixed_context_output_concurrency(contract: AlphaBetaContract) -> None:
+    lane = contract.lane("dense-distributed-gguf")
+    assert lane["context_tokens"] == 2048
+    assert lane["output_tokens"] == 128
+    assert list(lane["concurrency_levels"]) == [1, 4]
+
+
+def test_v4_lane_defines_separate_alpha_and_beta_scale(contract: AlphaBetaContract) -> None:
+    lane = contract.lane("v4-flash-distributed")
+    assert lane["alpha_context_tokens"] == 4096
+    assert list(lane["alpha_concurrency_levels"]) == [1, 4]
+    assert lane["beta_context_tokens"] == 16384
+    assert list(lane["beta_concurrency_levels"]) == [1, 4, 8, 16]
+    assert lane["hardware"]["mtp"].startswith("reserved and off for alpha")
+
+
+# --------------------------------------------------------------------------
+# Fixed prompts and sampling are shared, not per-lane free variables
+# --------------------------------------------------------------------------
+
+
+def test_prompt_set_is_fixed_and_referenced_by_id(contract_doc: dict) -> None:
+    prompt_ids = {p["id"] for p in contract_doc["prompt_set"]["prompts"]}
+    assert prompt_ids == {
+        "short-instruction",
+        "code-completion",
+        "multi-step-reasoning",
+        "long-context-fill",
+    }
+    for lane_name in ("dense-distributed-gguf", "v4-flash-distributed"):
+        lane = contract_doc["lanes"][lane_name]
+        for key in ("prompt_ids", "beta_prompt_ids"):
+            if key in lane:
+                assert set(lane[key]) <= prompt_ids
+
+
+def test_sampling_is_greedy(contract_doc: dict) -> None:
+    sampling = contract_doc["sampling"]
+    assert sampling["temperature"] == 0.0
+    assert sampling["top_p"] == 1.0
+    assert sampling["top_k"] == 1
+
+
+# --------------------------------------------------------------------------
+# Gain attribution separates quantization/model-fit from runtime/transport
+# --------------------------------------------------------------------------
+
+
+def test_gain_attribution_axes_are_disjoint(contract_doc: dict) -> None:
+    attribution = contract_doc["gain_attribution"]
+    fit_metrics = set(attribution["quantization_model_fit_metrics"])
+    runtime_metrics = set(attribution["runtime_transport_batching_kernel_metrics"])
+    assert fit_metrics, "quantization/model-fit axis must not be empty"
+    assert runtime_metrics, "runtime/transport/batching/kernel axis must not be empty"
+    assert fit_metrics.isdisjoint(runtime_metrics), (
+        "a metric cannot count as both a quantization/model-fit gain and a "
+        "runtime/transport/batching/kernel gain"
+    )
+
+
+# --------------------------------------------------------------------------
+# Quants and stage counts are named certification scenarios only
+# --------------------------------------------------------------------------
+
+
+def test_certification_scenarios_are_named_labels_not_defaults(contract_doc: dict) -> None:
+    scenarios = contract_doc["certification_scenarios"]
+    assert scenarios["stage_count"]["names"] == ["2-4-stage", "10-plus-stage"]
+    assert set(scenarios["quantization"]["names"]) == {"Q4_K_M", "Q8_0", "bf16-reference"}
+    for axis in ("stage_count", "quantization"):
+        assert "no product or runtime code path" in scenarios[axis]["rule"].lower()
+
+
+def test_no_product_module_hardcodes_the_named_stage_counts_or_quant() -> None:
+    """The contract may *name* '2-4-stage'/'10-plus-stage'/'Q4_K_M' as scenarios;
+    no runtime module outside this contract package and its evidence/spec
+    peers may hardcode them as product logic (e.g. `range(2, 5)` gating
+    placement, or a literal default quantization string)."""
+    repo_root = Path(__file__).resolve().parent.parent
+    node_pkg = repo_root / "packages" / "node" / "meshnet_node"
+    allowed_hits = {
+        node_pkg / "dgr_performance" / "contract.py",
+        node_pkg / "dgr_performance" / "data" / "alpha-beta-contract-v1.json",
+    }
+    offenders = []
+    for path in node_pkg.rglob("*.py"):
+        if "__pycache__" in path.parts or path in allowed_hits:
+            continue
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        if "2-4-stage" in text or "10-plus-stage" in text:
+            offenders.append(str(path))
+    assert not offenders, f"stage-count certification labels leaked into product code: {offenders}"
+
+
+# --------------------------------------------------------------------------
+# Alpha: correctness + human-approved useful speed
+# --------------------------------------------------------------------------
+
+
+def test_alpha_verdicts_are_exactly_alpha_optimize_stop(contract: AlphaBetaContract) -> None:
+    assert tuple(contract.alpha["verdicts"]) == ALPHA_VERDICTS == ("alpha", "optimize", "stop")
+
+
+def test_alpha_requires_correctness_thresholds(contract: AlphaBetaContract) -> None:
+    correctness = contract.alpha["correctness"]
+    assert correctness["min_greedy_token_agreement"] == 0.9
+    assert correctness["forbid_nonfinite_tensors"] is True
+    assert correctness["dense_attention_fallback_satisfies_alpha"] is False
+
+
+def test_alpha_useful_speed_requires_human_approval(contract: AlphaBetaContract) -> None:
+    useful_speed = contract.alpha["useful_speed"]
+    assert useful_speed["min_decode_speedup_vs_reference_baseline"] == 1.25
+    approval = useful_speed["human_approval"]
+    assert approval["required"] is True
+    assert approval["approved"] is False
+    assert approval["approved_by"] is None
+    assert approval["approved_at"] is None
+
+
+def test_alpha_holds_mtp_reserved_and_off(contract: AlphaBetaContract) -> None:
+    mtp = contract.alpha["mtp"]
+    assert mtp["reserved"] is True
+    assert mtp["enabled_for_alpha"] is False
+    assert mtp["ownership_contract_and_benchmark_required_before_beta"] is True
+
+
+def test_parse_contract_rejects_a_contract_missing_human_approval() -> None:
+    doc = json.loads(
+        Path("packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json")
+        .read_text(encoding="utf-8")
+    )
+    mutated = copy.deepcopy(doc)
+    mutated["alpha"]["useful_speed"]["human_approval"]["required"] = False
+    resealed = seal_contract({k: v for k, v in mutated.items() if k != "contract_sha256"})
+    with pytest.raises(DgrPerformanceContractError, match="human-approved useful-speed"):
+        parse_contract(resealed, source="<mutated>")
+
+
+# --------------------------------------------------------------------------
+# Beta: adds concurrency, long-context, failure, sustained-throughput
+# --------------------------------------------------------------------------
+
+
+def test_beta_verdicts_are_exactly_beta_targeted_optimization_stop_rollback(
+    contract: AlphaBetaContract,
+) -> None:
+    assert tuple(contract.beta["verdicts"]) == BETA_VERDICTS == (
+        "beta",
+        "targeted-optimization",
+        "stop-rollback",
+    )
+
+
+def test_beta_adds_exactly_the_four_required_axes(contract: AlphaBetaContract) -> None:
+    assert set(contract.beta["adds"]) == {
+        "concurrency",
+        "long_context",
+        "failure",
+        "sustained_throughput",
+    }
+    for axis in contract.beta["adds"]:
+        assert axis in contract.beta
+
+
+def test_beta_long_context_matches_the_v4_lane_beta_scale(contract: AlphaBetaContract) -> None:
+    assert contract.beta["long_context"]["context_tokens"] == 16384
+    assert contract.beta["long_context"]["context_tokens"] == contract.lane(
+        "v4-flash-distributed"
+    )["beta_context_tokens"]
+
+
+def test_beta_failure_axis_forbids_silent_kv_migration(contract: AlphaBetaContract) -> None:
+    failure = contract.beta["failure"]
+    assert failure["forbid_silent_kv_migration"] is True
+    assert failure["synthetic_workers_satisfy_beta"] is False
+
+
+# --------------------------------------------------------------------------
+# Immutability: mutation after sealing is rejected, not silently trusted
+# --------------------------------------------------------------------------
+
+
+def test_parse_contract_rejects_a_mutated_threshold() -> None:
+    doc = json.loads(
+        Path("packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json")
+        .read_text(encoding="utf-8")
+    )
+    mutated = copy.deepcopy(doc)
+    mutated["alpha"]["useful_speed"]["min_decode_speedup_vs_reference_baseline"] = 1.01
+    with pytest.raises(DgrPerformanceContractError, match="modified since it was locked"):
+        parse_contract(mutated, source="<mutated>")
+
+
+def test_parse_contract_rejects_a_resealed_mutation_against_the_pinned_digest() -> None:
+    doc = json.loads(
+        Path("packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json")
+        .read_text(encoding="utf-8")
+    )
+    mutated = copy.deepcopy(doc)
+    mutated["alpha"]["useful_speed"]["min_decode_speedup_vs_reference_baseline"] = 1.01
+    resealed = seal_contract({k: v for k, v in mutated.items() if k != "contract_sha256"})
+    with pytest.raises(DgrPerformanceContractError, match="re-sealed mutation"):
+        parse_contract(resealed, source="<resealed>")
+
+
+def test_parse_contract_rejects_missing_digest() -> None:
+    doc = json.loads(
+        Path("packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json")
+        .read_text(encoding="utf-8")
+    )
+    stripped = {k: v for k, v in doc.items() if k != "contract_sha256"}
+    with pytest.raises(DgrPerformanceContractError, match="carries no contract_sha256"):
+        parse_contract(stripped, source="<stripped>")
+
+
+def test_load_contract_from_explicit_path_matches_packaged_load(contract: AlphaBetaContract) -> None:
+    on_disk = load_contract(
+        Path("packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json")
+    )
+    assert on_disk.digest == contract.digest
+    assert on_disk.to_dict() == contract.to_dict()
+
+
+def test_seal_contract_is_the_only_supported_way_to_produce_a_digest(contract_doc: dict) -> None:
+    unsigned = {k: v for k, v in contract_doc.items() if k != "contract_sha256"}
+    sealed = seal_contract(unsigned)
+    assert sealed["contract_sha256"] == CONTRACT_V1_SHA256
+
+
+def test_amendment_policy_is_locked_and_nonempty(contract: AlphaBetaContract) -> None:
+    assert "new contract_id" in contract.amendment_policy
+    assert "human review" in contract.amendment_policy