feat: checkpoint distributed gguf runtime stories

tests/test_tracker_capability_admission.py

@@ -5,6 +5,7 @@ Model ids here are arbitrary and made up on purpose: nothing in the admission or
 routing path may branch on a vendor, model or kernel name.
 """
 
+import hashlib
 import json
 import time
 import urllib.error
@@ -18,6 +19,7 @@ from meshnet_tracker.capability import (
     POLICY_ENFORCE,
     STATE_ABSENT,
     STATE_ADMITTED,
+    STATE_COMPATIBILITY_MISMATCH,
     STATE_CATALOGUE_INCOMPATIBLE,
     STATE_FAILED,
     STATE_INVALID,
@@ -41,6 +43,14 @@ SHORT = "oracle-9b"
 LAYERS = 32
 
 
+def _stable_json(data: dict) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _sha256_text(data: dict) -> str:
+    return "sha256:" + hashlib.sha256(_stable_json(data).encode("utf-8")).hexdigest()
+
+
 def _post_json(url: str, payload: dict) -> dict:
     data = json.dumps(payload).encode()
     req = urllib.request.Request(
@@ -60,6 +70,8 @@ def _report(
     model_id: str = MODEL,
     start: int = 0,
     end: int = 15,
+    owns_embedding: bool | None = None,
+    owns_final_head: bool | None = None,
     status: str = "passed",
     validated_at: float | None = None,
     recipe_id: str = "baseline",
@@ -70,10 +82,48 @@ def _report(
     diagnostics: list | None = None,
 ) -> dict:
     """A capability report shaped exactly as `meshnet_node.capability` emits it."""
-    return {
+    if owns_embedding is None:
+        owns_embedding = start == 0
+    if owns_final_head is None:
+        owns_final_head = end >= LAYERS - 1
+    artifact = {
+        "model_id": model_id,
+        "revision": None,
+        "artifact_hash": _sha256_text(
+            {
+                "model_id": model_id,
+                "shard_start": start,
+                "shard_end": end,
+                "recipe_id": recipe_id,
+                "recipe_version": recipe_version,
+            }
+        ),
+        "shard_start": start,
+        "shard_end": end,
+    }
+    runtime_recipe = {
+        "weight_quantization": "bfloat16",
+        "activation_dtype": "bfloat16",
+        "compute_dtype": "bfloat16",
+        "kv_dtype": "bfloat16",
+        "kv_layout": "session-cache",
+        "tokenizer_revision": model_id,
+        "architecture_adapter": "unknown",
+        "backend_id": "torch-transformers",
+        "runtime_version": "0.1.0",
+        "boundary_schema_version": 1,
+        "cache_layout": "local-hot-kv",
+    }
+    runtime_recipe["fingerprint"] = _sha256_text(runtime_recipe)
+    payload = {
         "schema_version": schema_version,
         "model": {"model_id": model_id, "revision": None, "config_fingerprint": None},
-        "shard": {"start": start, "end": end},
+        "shard": {
+            "start": start,
+            "end": end,
+            "owns_embedding": owns_embedding,
+            "owns_final_head": owns_final_head,
+        },
         "recipe": {
             "recipe_id": recipe_id,
             "recipe_version": recipe_version,
@@ -86,11 +136,24 @@ def _report(
             "quantization": "bfloat16",
             "runtime": {},
         },
+        "artifact": artifact,
+        "runtime_recipe": runtime_recipe,
         "status": status,
         "validated_at": time.time() if validated_at is None else validated_at,
         "duration_ms": 42,
         "diagnostics": list(diagnostics or []),
     }
+    payload["compatibility_fingerprint"] = _sha256_text(
+        {
+            "model": payload["model"],
+            "shard": payload["shard"],
+            "recipe": payload["recipe"],
+            "backend": payload["backend"],
+            "artifact": payload["artifact"],
+            "runtime_recipe": payload["runtime_recipe"],
+        }
+    )
+    return payload
 
 
 def _registration(
@@ -119,6 +182,7 @@ def _registration(
         report = _report(start=start, end=end)
     if report is not None:
         payload["capability_report"] = report
+        payload["compatibility_fingerprint"] = report["compatibility_fingerprint"]
     if recipe_id is not None:
         payload["recipe_id"] = recipe_id
     if recipe_version is not None:
@@ -196,6 +260,15 @@ def test_a_report_for_a_different_recipe_than_the_node_declares_is_a_recipe_mism
     assert versioned.state == STATE_RECIPE_MISMATCH
 
 
+def test_a_report_for_a_different_compatibility_fingerprint_is_a_compatibility_mismatch():
+    "The exact artifact/runtime recipe fingerprint gates admission.\n\nTags: routing, tracker"
+    state = _evaluate(
+        _report(),
+        declared_compatibility_fingerprint="sha256:deadbeef",
+    )
+    assert state.state == STATE_COMPATIBILITY_MISMATCH
+
+
 def test_an_older_recipe_catalogue_is_incompatible():
     "Recipe ids from a catalogue older than the tracker's minimum cannot be matched.\n\nTags: routing, tracker"
     state = _evaluate(_report(catalogue_version="2025.01.1"))