feat: DGR-003 - Define exact Artifact and runtime recipe identity

packages/tracker/meshnet_tracker/capability.py

@@ -30,6 +30,13 @@ import time
 from dataclasses import dataclass, replace
 from typing import Any, Callable, Mapping
 
+from .recipe import (
+    CertificationLedger,
+    FingerprintMismatch,
+    RecipeIdentityError,
+    parse_identity,
+)
+
 # The capability report layout this tracker reads (meshnet_node.capability).
 SUPPORTED_SCHEMA_VERSION = 1
 
@@ -58,6 +65,12 @@ STATE_MODEL_MISMATCH = "model-mismatch"
 STATE_SHARD_MISMATCH = "shard-mismatch"
 STATE_RECIPE_MISMATCH = "recipe-mismatch"
 STATE_CATALOGUE_INCOMPATIBLE = "catalogue-incompatible"
+# The node presented a DGR-003 identity block whose declared fingerprint is not
+# the digest of the axes it declared. Identity is derived, never asserted.
+STATE_FINGERPRINT_MISMATCH = "fingerprint-mismatch"
+# Registered-but-dark: a known recipe no real distributed forward has certified.
+# Visible to an operator, never routable for user traffic.
+STATE_UNCERTIFIED = "uncertified"
 
 ALL_STATES = (
     STATE_ADMITTED,
@@ -69,6 +82,8 @@ ALL_STATES = (
     STATE_SHARD_MISMATCH,
     STATE_RECIPE_MISMATCH,
     STATE_CATALOGUE_INCOMPATIBLE,
+    STATE_FINGERPRINT_MISMATCH,
+    STATE_UNCERTIFIED,
 )
 
 # --- Compatibility policy for nodes that predate the capability protocol. ---
@@ -165,12 +180,25 @@ class CapabilityState:
     recorded_at: float = 0.0
     schema_version: int | None = None
     diagnostics: tuple[str, ...] = ()
+    # The DGR-003 compatibility fingerprint, *re-derived* by this tracker from
+    # the axes the node declared — never copied from what the node claimed.
+    # Absent for a node that predates DGR-003.
+    model_artifact_digest: str | None = None
+    runtime_recipe_digest: str | None = None
+    certification: str | None = None
 
     @property
     def proven(self) -> bool:
         """The presented proof covers exactly what the node advertised."""
         return self.state == STATE_ADMITTED
 
+    @property
+    def fingerprint(self) -> tuple[str, str] | None:
+        """What route formation compares. `None` when the node declares no identity."""
+        if self.model_artifact_digest is None or self.runtime_recipe_digest is None:
+            return None
+        return (self.model_artifact_digest, self.runtime_recipe_digest)
+
     def routable_under(self, policy: str) -> bool:
         if self.proven:
             return True
@@ -197,6 +225,9 @@ class CapabilityState:
             "recorded_at": self.recorded_at,
             "schema_version": self.schema_version,
             "diagnostics": list(self.diagnostics),
+            "model_artifact_digest": self.model_artifact_digest,
+            "runtime_recipe_digest": self.runtime_recipe_digest,
+            "certification": self.certification,
         }
 
 
@@ -224,6 +255,7 @@ def evaluate_report(
     declared_recipe_version: str | None = None,
     now: float | None = None,
     max_age_seconds: float = DEFAULT_MAX_REPORT_AGE_SECONDS,
+    ledger: CertificationLedger | None = None,
 ) -> CapabilityState:
     """Judge the proof a node presented against what that node is advertising.
 
@@ -308,6 +340,67 @@ def evaluate_report(
             f"the node declared v{declared_recipe_version}",
         )
 
+    identity = None
+    if report.get("identity") is not None:
+        try:
+            identity = parse_identity(report["identity"])
+        except FingerprintMismatch as exc:
+            return base.with_state(STATE_FINGERPRINT_MISMATCH, str(exc))
+        except RecipeIdentityError as exc:
+            return base.with_state(
+                STATE_INVALID, f"capability identity block is unusable: {exc}"
+            )
+
+        # The report's `shard` range is inclusive/inclusive (the CLI and backend
+        # convention); the identity's is inclusive/exclusive (the protocol's, and
+        # ADR-0012's). A node whose two halves disagree has not proven the range
+        # it claims, whichever one is right.
+        if (identity.shard_start, identity.shard_end) != (
+            base.shard_start,
+            (base.shard_end or 0) + 1,
+        ):
+            return base.with_state(
+                STATE_SHARD_MISMATCH,
+                f"identity covers layers {identity.shard_start}–{identity.shard_end} "
+                f"(end-exclusive), but the proof is for layers {base.shard_start}–"
+                f"{base.shard_end} (end-inclusive)",
+            )
+
+        if not model_matches(identity.artifact_id):
+            return base.with_state(
+                STATE_MODEL_MISMATCH,
+                f"identity is for artifact {identity.artifact_id!r}, but the node "
+                f"registered {advertised_model!r}",
+            )
+        if (
+            identity.recipe_id != base.recipe_id
+            or identity.recipe_version != base.recipe_version
+            or identity.catalogue_version != base.catalogue_version
+        ):
+            return base.with_state(
+                STATE_RECIPE_MISMATCH,
+                "identity recipe labels do not match the capability proof",
+            )
+        if identity.axes["backend_id"] != base.backend_id:
+            return base.with_state(
+                STATE_RECIPE_MISMATCH,
+                "identity backend does not match the capability proof",
+            )
+        if (
+            base.quantization is not None
+            and identity.axes["weight_quantization"] != base.quantization
+        ):
+            return base.with_state(
+                STATE_RECIPE_MISMATCH,
+                "identity weight quantization does not match the capability proof",
+            )
+
+        base = replace(
+            base,
+            model_artifact_digest=identity.model_artifact_digest,
+            runtime_recipe_digest=identity.runtime_recipe_digest,
+        )
+
     if status != STATUS_PASSED:
         return base.with_state(
             STATE_FAILED,
@@ -328,6 +421,15 @@ def evaluate_report(
             f"proof is timestamped {-age:.0f}s in the future; check the node's clock",
         )
 
+    # The digest only establishes that this report is self-consistent. It does
+    # not authenticate a node or prove a distributed forward. Exact recipes are
+    # therefore registered-but-dark until tracker-owned certification records
+    # that forward.
+    if identity is not None:
+        recipe_status = (ledger or CertificationLedger()).register(identity)
+        if not recipe_status.may_serve:
+            return base.with_state(STATE_UNCERTIFIED, recipe_status.detail)
+
     return base.with_state(
         STATE_ADMITTED,
         f"{base.model_id} layers {base.shard_start}–{base.shard_end} proven on "