story: DGR-041 Register native Shard capabilities without redesigning Meshnet

packages/node/meshnet_node/capability.py

@@ -322,6 +322,49 @@ class BackendIdentity:
         )
 
 
+@dataclass(frozen=True)
+class ExecutionCapacity:
+    """Backend-neutral limits reserved for one registered capability.
+
+    The optional shape preserves existing Transformers reports unchanged while
+    allowing a native Shard to state its measured/admitted resource envelope.
+    """
+
+    memory_capacity_bytes: int | None = None
+    kv_capacity_tokens: int | None = None
+    max_concurrent_sessions: int | None = None
+
+    def __post_init__(self) -> None:
+        for name in (
+            "memory_capacity_bytes",
+            "kv_capacity_tokens",
+            "max_concurrent_sessions",
+        ):
+            value = getattr(self, name)
+            if value is not None:
+                _require_int(value, f"capacity.{name}", 1)
+
+    def to_dict(self) -> dict:
+        return {
+            "memory_capacity_bytes": self.memory_capacity_bytes,
+            "kv_capacity_tokens": self.kv_capacity_tokens,
+            "max_concurrent_sessions": self.max_concurrent_sessions,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Any) -> ExecutionCapacity:
+        doc = _as_mapping(data, "capacity")
+        values: dict[str, int | None] = {}
+        for name in (
+            "memory_capacity_bytes",
+            "kv_capacity_tokens",
+            "max_concurrent_sessions",
+        ):
+            value = doc.get(name)
+            values[name] = None if value is None else _require_int(value, f"capacity.{name}", 1)
+        return cls(**values)
+
+
 def _as_mapping(data: Any, field_name: str) -> Mapping[str, Any]:
     if not isinstance(data, Mapping):
         raise CapabilityReportError(
@@ -353,6 +396,7 @@ class CapabilityReport:
     diagnostics: tuple[str, ...] = ()
     schema_version: int = CAPABILITY_SCHEMA_VERSION
     identity: ShardIdentity | None = None
+    capacity: ExecutionCapacity | None = None
 
     def __post_init__(self) -> None:
         if self.status not in VALID_STATUSES:
@@ -410,6 +454,8 @@ class CapabilityReport:
         }
         if self.identity is not None:
             doc["identity"] = self.identity.to_dict()
+        if self.capacity is not None:
+            doc["capacity"] = self.capacity.to_dict()
         return doc
 
     def to_json(self, indent: int | None = None) -> str:
@@ -451,6 +497,9 @@ class CapabilityReport:
             identity=(
                 None if raw_identity is None else ShardIdentity.from_dict(raw_identity)
             ),
+            capacity=(
+                None if doc.get("capacity") is None else ExecutionCapacity.from_dict(doc["capacity"])
+            ),
         )
 
     @classmethod
@@ -486,6 +535,7 @@ def build_capability_report(
     validated_at: float | None = None,
     environ: Mapping[str, str] | None = None,
     identity: ShardIdentity | None = None,
+    capacity: ExecutionCapacity | None = None,
 ) -> CapabilityReport:
     """Assemble a report from flat validation results.
 
@@ -518,4 +568,5 @@ def build_capability_report(
         duration_ms=duration_ms,
         diagnostics=sanitize_diagnostics(diagnostics, environ),
         identity=identity,
+        capacity=capacity,
     )

packages/node/meshnet_node/native_registration.py

@@ -0,0 +1,160 @@
+"""Register a verified native Shard through the ordinary capability contract.
+
+This is intentionally an adapter, not a second tracker protocol.  It converts
+the native worker's immutable identity and enforced resource limits into the
+same capability report every backend may submit.  The tracker remains the sole
+owner of certification and decides whether the visible registration is dark.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .capability import ExecutionCapacity, build_capability_report
+from .native_worker_supervisor import NativeWorkerProbe, NativeWorkerSpec, NativeWorkerSupervisor
+from .runtime_recipe import ShardIdentity
+
+
+class NativeRegistrationError(ValueError):
+    """Native facts do not describe one coherent, registerable Shard."""
+
+
+@dataclass(frozen=True)
+class NativeShardRegistration:
+    """One backend-neutral registration payload for a verified native Shard."""
+
+    endpoint: str
+    model_id: str
+    identity: ShardIdentity
+    worker: NativeWorkerSpec
+    probe: NativeWorkerProbe
+    device: str
+    capacity: ExecutionCapacity
+    duration_ms: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.endpoint:
+            raise NativeRegistrationError("native registration requires an endpoint")
+        if not self.model_id:
+            raise NativeRegistrationError("native registration requires a model id")
+        if not self.device:
+            raise NativeRegistrationError("native registration requires a device label")
+        if self.identity.artifact.artifact_id != self.model_id:
+            raise NativeRegistrationError("native registration model does not match its identity")
+        if self.identity.fingerprint.model_artifact_digest != self.worker.artifact_digest:
+            raise NativeRegistrationError("native worker artifact digest does not match its identity")
+        if self.identity.fingerprint.runtime_recipe_digest != self.worker.recipe_digest:
+            raise NativeRegistrationError("native worker recipe digest does not match its identity")
+        expected = (
+            self.worker.artifact_digest,
+            self.worker.recipe_digest,
+            self.worker.recipe_id,
+            self.worker.recipe_version,
+            self.worker.catalogue_version,
+            self.worker.shard_start,
+            self.worker.shard_end,
+        )
+        actual = (
+            self.probe.artifact_digest,
+            self.probe.recipe_digest,
+            self.probe.recipe_id,
+            self.probe.recipe_version,
+            self.probe.catalogue_version,
+            self.probe.shard_start,
+            self.probe.shard_end,
+        )
+        if actual != expected:
+            raise NativeRegistrationError("native worker probe differs from its startup identity/range")
+        if not self.probe.serving:
+            raise NativeRegistrationError("native worker is not serving; it cannot register a capability")
+        if (
+            self.identity.shard_start,
+            self.identity.shard_end,
+            self.identity.recipe.recipe_id,
+            self.identity.recipe.recipe_version,
+            self.identity.recipe.catalogue_version,
+        ) != (
+            self.worker.shard_start,
+            self.worker.shard_end,
+            self.worker.recipe_id,
+            self.worker.recipe_version,
+            self.worker.catalogue_version,
+        ):
+            raise NativeRegistrationError("native identity differs from worker range or recipe labels")
+        if self.identity.recipe.axes["backend_id"] == "":
+            raise NativeRegistrationError("native identity must name its backend")
+
+    def payload(self) -> dict[str, Any]:
+        """Return the existing tracker registration shape with no native branch."""
+        report = build_capability_report(
+            model_id=self.model_id,
+            shard_start=self.identity.shard_start,
+            shard_end=self.identity.shard_end - 1,
+            recipe_id=self.identity.recipe.recipe_id,
+            recipe_version=self.identity.recipe.recipe_version,
+            catalogue_version=self.identity.recipe.catalogue_version,
+            backend_id=self.identity.recipe.axes["backend_id"],
+            device=self.device,
+            quantization=self.identity.recipe.axes["weight_quantization"],
+            model_config="sha256:" + self.identity.artifact.architecture_digest,
+            revision=self.identity.artifact.revision,
+            status="passed",
+            duration_ms=self.duration_ms,
+            identity=self.identity,
+            capacity=self.capacity,
+        )
+        return {
+            "endpoint": self.endpoint,
+            "model": self.model_id.rsplit("/", 1)[-1],
+            "hf_repo": self.model_id,
+            "shard_start": self.identity.shard_start,
+            "shard_end": self.identity.shard_end - 1,
+            "recipe_id": self.identity.recipe.recipe_id,
+            "recipe_version": self.identity.recipe.recipe_version,
+            "capability_report": report.to_dict(),
+            # Existing tracker capacity fields are retained for placement views.
+            "ram_bytes": self.capacity.memory_capacity_bytes or 0,
+            "max_loaded_shards": 1,
+        }
+
+
+RegistrationSender = Callable[[dict[str, Any]], None]
+WithdrawalSender = Callable[[str], None]
+
+
+class NativeCapabilityRegistrar:
+    """Publish/withdraw a native capability through caller-owned transport.
+
+    The callbacks keep tracker HTTP, relay, billing, and provider mechanics out
+    of the native worker.  A process supervisor calls ``withdraw`` on health
+    loss; the caller supplies the existing tracker registration/withdrawal
+    transport appropriate to its deployment.
+    """
+
+    def __init__(
+        self,
+        registration: NativeShardRegistration,
+        *,
+        register: RegistrationSender,
+        withdraw: WithdrawalSender,
+    ) -> None:
+        self.registration = registration
+        self._register = register
+        self._withdraw = withdraw
+
+    def publish(self) -> None:
+        self._register(self.registration.payload())
+
+    def unavailable(self, reason: str) -> None:
+        self._withdraw(reason)
+
+    def bind(self, supervisor: NativeWorkerSupervisor) -> None:
+        """Publish only after DGR-040 verification; withdraw on health loss."""
+        if supervisor.spec != self.registration.worker:
+            raise NativeRegistrationError("registrar and supervisor must own the same native worker")
+        supervisor.add_availability_callbacks(
+            on_available=lambda _reason: self.publish(),
+            on_unavailable=self.unavailable,
+        )

packages/node/meshnet_node/native_worker_supervisor.py

@@ -220,6 +220,23 @@ class NativeWorkerSupervisor:
             self._on_available("worker ready and identity verified")
         return result
 
+    def add_availability_callbacks(
+        self,
+        *,
+        on_available: AvailabilityCallback | None = None,
+        on_unavailable: AvailabilityCallback | None = None,
+    ) -> None:
+        """Attach an integration callback before the worker is started.
+
+        Registration is deliberately supplied by the caller so this supervisor
+        stays independent of Tracker HTTP and of every other backend.
+        """
+        with self._lock:
+            if self._process is not None:
+                raise NativeWorkerError("availability callbacks must be attached before start")
+            self._on_available = _combine_callbacks(self._on_available, on_available)
+            self._on_unavailable = _combine_callbacks(self._on_unavailable, on_unavailable)
+
     def restart(self) -> NativeWorkerProbe:
         """Withdraw the old capability, stop its process, then prove a fresh one."""
         self.stop(reason="worker restart requested")
@@ -330,6 +347,21 @@ def _sha256_file(path: Path) -> str:
     return digest.hexdigest()
 
 
+def _combine_callbacks(
+    first: AvailabilityCallback | None, second: AvailabilityCallback | None
+) -> AvailabilityCallback | None:
+    if first is None:
+        return second
+    if second is None:
+        return first
+
+    def combined(reason: str) -> None:
+        first(reason)
+        second(reason)
+
+    return combined
+
+
 def _terminate_process_group(
     process: subprocess.Popen[str], shutdown_timeout: float, kill_timeout: float
 ) -> None:

packages/tracker/meshnet_tracker/capability.py

@@ -190,6 +190,9 @@ class CapabilityState:
     # ("dark"/"certified"), so the network map answers "why is this exact node
     # not routing" without a second query. None when no identity was presented.
     certification: str | None = None
+    memory_capacity_bytes: int | None = None
+    kv_capacity_tokens: int | None = None
+    max_concurrent_sessions: int | None = None
 
     @property
     def proven(self) -> bool:
@@ -233,6 +236,9 @@ class CapabilityState:
             "runtime_recipe_digest": self.runtime_recipe_digest,
             "shard_binding_digest": self.shard_binding_digest,
             "certification": self.certification,
+            "memory_capacity_bytes": self.memory_capacity_bytes,
+            "kv_capacity_tokens": self.kv_capacity_tokens,
+            "max_concurrent_sessions": self.max_concurrent_sessions,
         }
 
 
@@ -491,6 +497,10 @@ def _parse_report(doc: Mapping[str, Any]) -> dict:
     if isinstance(schema_version, bool) or not isinstance(schema_version, int):
         raise _ReportError("'schema_version' must be an integer")
 
+    capacity = doc.get("capacity")
+    if capacity is not None:
+        capacity = _object(capacity, "capacity")
+
     return {
         "model_id": _text(model.get("model_id"), "model.model_id"),
         "shard_start": _index(shard.get("start"), "shard.start"),
@@ -508,6 +518,18 @@ def _parse_report(doc: Mapping[str, Any]) -> dict:
         "validated_at": float(validated_at),
         "schema_version": schema_version,
         "diagnostics": _diagnostics(doc.get("diagnostics")),
+        "memory_capacity_bytes": _optional_positive_int(
+            None if capacity is None else capacity.get("memory_capacity_bytes"),
+            "capacity.memory_capacity_bytes",
+        ),
+        "kv_capacity_tokens": _optional_positive_int(
+            None if capacity is None else capacity.get("kv_capacity_tokens"),
+            "capacity.kv_capacity_tokens",
+        ),
+        "max_concurrent_sessions": _optional_positive_int(
+            None if capacity is None else capacity.get("max_concurrent_sessions"),
+            "capacity.max_concurrent_sessions",
+        ),
         "_status": _text(doc.get("status"), "status"),
     }
 
@@ -536,6 +558,14 @@ def _index(value: Any, field_name: str) -> int:
     return value
 
 
+def _optional_positive_int(value: Any, field_name: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise _ReportError(f"{field_name!r} must be a positive integer")
+    return value
+
+
 def _maybe_int(value: Any) -> int | None:
     if isinstance(value, bool) or not isinstance(value, int):
         return None