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

packages/node/meshnet_node/capability.py

@@ -20,6 +20,8 @@ import time
 from dataclasses import dataclass, field
 from typing import Any, Mapping
 
+from .runtime_recipe import CompatibilityFingerprint, ShardIdentity
+
 # Layout of the serialized report. Bump when the JSON shape changes.
 CAPABILITY_SCHEMA_VERSION = 1
 
@@ -330,7 +332,16 @@ def _as_mapping(data: Any, field_name: str) -> Mapping[str, Any]:
 
 @dataclass(frozen=True)
 class CapabilityReport:
-    """One node's validated (or failed) model/shard/recipe/backend combination."""
+    """One node's validated (or failed) model/shard/recipe/backend combination.
+
+    `identity` is the exact DGR-003 artifact/runtime-recipe block: the separated
+    numerical axes and the compatibility fingerprint derived from them. It is
+    optional and additive — a node that predates DGR-003 presents none, and the
+    tracker falls back to the coarse label comparison it has always done
+    (ADR-0023's compat rollout). A node that *does* present one is held to it:
+    the tracker re-derives the fingerprint and refuses a report whose claim does
+    not match its own derivation.
+    """
 
     model: ModelIdentity
     shard: ShardRange
@@ -341,6 +352,7 @@ class CapabilityReport:
     duration_ms: int
     diagnostics: tuple[str, ...] = ()
     schema_version: int = CAPABILITY_SCHEMA_VERSION
+    identity: ShardIdentity | None = None
 
     def __post_init__(self) -> None:
         if self.status not in VALID_STATUSES:
@@ -360,6 +372,11 @@ class CapabilityReport:
     def passed(self) -> bool:
         return self.status == STATUS_PASSED
 
+    @property
+    def fingerprint(self) -> CompatibilityFingerprint | None:
+        """The exact compatibility fingerprint, when this node declares one."""
+        return None if self.identity is None else self.identity.fingerprint
+
     def identity_key(self) -> tuple[str, int, int, str, str, str, str]:
         """The tuple a consumer must match to reuse this proof.
 
@@ -380,7 +397,7 @@ class CapabilityReport:
         return max(0.0, (time.time() if now is None else now) - self.validated_at)
 
     def to_dict(self) -> dict:
-        return {
+        doc = {
             "schema_version": self.schema_version,
             "model": self.model.to_dict(),
             "shard": self.shard.to_dict(),
@@ -391,6 +408,9 @@ class CapabilityReport:
             "duration_ms": self.duration_ms,
             "diagnostics": list(self.diagnostics),
         }
+        if self.identity is not None:
+            doc["identity"] = self.identity.to_dict()
+        return doc
 
     def to_json(self, indent: int | None = None) -> str:
         return json.dumps(self.to_dict(), indent=indent, sort_keys=True)
@@ -417,6 +437,7 @@ class CapabilityReport:
         ):
             raise CapabilityReportError("'validated_at' must be a Unix timestamp")
 
+        raw_identity = doc.get("identity")
         return cls(
             schema_version=schema_version,
             model=ModelIdentity.from_dict(doc.get("model")),
@@ -427,6 +448,9 @@ class CapabilityReport:
             validated_at=float(validated_at),
             duration_ms=_require_int(doc.get("duration_ms"), "duration_ms", 0),
             diagnostics=sanitize_diagnostics(doc.get("diagnostics")),
+            identity=(
+                None if raw_identity is None else ShardIdentity.from_dict(raw_identity)
+            ),
         )
 
     @classmethod
@@ -461,12 +485,14 @@ def build_capability_report(
     diagnostics: Any = None,
     validated_at: float | None = None,
     environ: Mapping[str, str] | None = None,
+    identity: ShardIdentity | None = None,
 ) -> CapabilityReport:
     """Assemble a report from flat validation results.
 
     `model_config` may be the loaded config mapping (hashed into a fingerprint)
     or an already-computed ``sha256:…`` string. `validated_at` defaults to now,
-    so callers that need determinism pass it explicitly.
+    so callers that need determinism pass it explicitly. `identity` is the exact
+    DGR-003 artifact/recipe block, when the backend can state one.
     """
     return CapabilityReport(
         model=ModelIdentity(
@@ -491,4 +517,5 @@ def build_capability_report(
         validated_at=time.time() if validated_at is None else validated_at,
         duration_ms=duration_ms,
         diagnostics=sanitize_diagnostics(diagnostics, environ),
+        identity=identity,
     )