feat: compare safetensors and gguf on cpu and gpu

feat: add DGR-001 performance contract
chore: wrap up completed story metadata
2026-07-14 18:45:12 +03:00 · 2026-07-14 18:13:54 +03:00 · 2026-07-14 17:09:04 +03:00 · 2026-07-14 17:01:08 +03:00 · 2026-07-14 16:00:37 +02:00 · 2026-07-14 15:55:24 +02:00
15 changed files with 701 additions and 47 deletions
--- a/.scratch/dashboard-test-runner/PRD.md
+++ b/.scratch/dashboard-test-runner/PRD.md
@@ -12,4 +12,10 @@ Provide an opt-in, admin-only tracker Dashboard Testing tab that dynamically dis
 - One active run.
 - Real inference stays separately environment-gated and excluded from default suites.

+## Operator workflow
+
+See [`docs/dev/dashboard-test-runner.md`](../../docs/dev/dashboard-test-runner.md)
+for launch configuration, default safe suites vs the gated real-inference suite,
+and required environment variables.
+
 See `prd.json` for executable Ralph user stories and acceptance criteria.
--- a/.scratch/dashboard-test-runner/prd.json
+++ b/.scratch/dashboard-test-runner/prd.json
@@ -51,15 +51,16 @@
        "uv run pytest tests/test_dashboard.py tests/test_dynamic_routing.py -q passes."
      ],
      "priority": 3,
-      "passes": false,
+      "passes": true,
      "notes": "Do not reintroduce --enable-test-runner without implementing its CLI argument in US-001.",
      "dependsOn": [
        "US-001",
        "US-002"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
    }
  ],
  "metadata": {
-    "updatedAt": "2026-07-11T17:02:30.520Z"
+    "updatedAt": "2026-07-12T01:58:06.286Z"
  }
 }
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-001/README.md
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-001/README.md
@@ -0,0 +1,68 @@
+# DGR-001 — performance contract baseline
+
+## Files changed
+
+- `packages/node/meshnet_node/performance_contract.py`
+- `tests/test_performance_contract.py`
+- `.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json`
+
+## What this slice does
+
+- Locks the DGR-001 benchmark contract in code.
+- Pins the architecture-aligned baseline to **DeepSeek-V2-Lite-Chat** (`deepseek2`).
+- Uses the same model on both sides of the comparison:
+  - **safetensors:** `deepseek-ai/DeepSeek-V2-Lite-Chat` in **BF16**
+  - **GGUF:** `second-state/DeepSeek-V2-Lite-Chat-GGUF` in **Q2_K**
+- Exposes a machine-readable JSON contract with:
+  - benchmark lanes for `transformers` safetensors and `llama.cpp` GGUF on **CPU** and **GPU**
+  - concurrency levels `1` and `4`
+  - the required metrics list
+  - an explicit stop condition for “no meaningful speed or fit benefit”
+
+## Exact commands and real results
+
+### Targeted tests
+
+```bash
+pytest -q tests/test_performance_contract.py tests/test_route_session_benchmark.py
+```
+
+Result: `9 passed in 0.14s`
+
+### Contract artifact generation
+
+```bash
+PYTHONPATH=packages/node python -m meshnet_node.performance_contract --json-out .scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json
+```
+
+Result: wrote `.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json`
+
+### Python compile check
+
+```bash
+python -m compileall packages/node/meshnet_node/performance_contract.py tests/test_performance_contract.py
+```
+
+Result: passed
+
+## Limitations
+
+- This slice captures the DGR-001 contract and baseline selection only.
+- It does **not** download or run a real model yet.
+- Real safetensors vs GGUF execution, TTFT/prefill/decode measurements, RSS/VRAM capture, and output-drift comparison are still to be implemented against the contract.
+
+## Compatibility notes
+
+- The contract stays on the DeepSeek2 family to remain close to the DeepSeek-V4-Flash end goal.
+- A smaller non-DeepSeek model can still be used later for loader-plumbing smoke tests, but it does not replace this baseline.
+- Model artifacts must stay on the mounted drive and not under `/home`.
+
+## Dependent-story handoff
+
+Next implementation work should attach to this contract and add the live benchmark runner that actually compares:
+
+1. current Transformers/safetensors recipe
+2. whole-model llama.cpp GGUF recipe
+
+using the same model architecture/revision and the same prompt/context/concurrency settings.
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json
@@ -0,0 +1,75 @@
+{
+  "benchmark_lanes": [
+    {
+      "concurrency_levels": [
+        1,
+        4
+      ],
+      "device": "cpu",
+      "id": "transformers-safetensors-cpu",
+      "recipe": "current safetensors recipe",
+      "runtime": "transformers"
+    },
+    {
+      "concurrency_levels": [
+        1,
+        4
+      ],
+      "device": "cpu",
+      "id": "llama-cpp-gguf-cpu",
+      "recipe": "whole-model GGUF recipe",
+      "runtime": "llama.cpp"
+    },
+    {
+      "concurrency_levels": [
+        1,
+        4
+      ],
+      "device": "gpu",
+      "id": "transformers-safetensors-gpu",
+      "recipe": "current safetensors recipe",
+      "runtime": "transformers"
+    },
+    {
+      "concurrency_levels": [
+        1,
+        4
+      ],
+      "device": "gpu",
+      "id": "llama-cpp-gguf-gpu",
+      "recipe": "whole-model GGUF recipe",
+      "runtime": "llama.cpp"
+    }
+  ],
+  "metrics": [
+    "ttft_ms",
+    "prefill_tok_per_sec",
+    "decode_tok_per_sec",
+    "p50_latency_ms",
+    "p95_latency_ms",
+    "aggregate_throughput_tok_per_sec",
+    "rss_bytes",
+    "vram_bytes",
+    "artifact_bytes",
+    "failure_count",
+    "output_drift"
+  ],
+  "model_target": {
+    "architecture": "deepseek2",
+    "comparison_policy": "same model/revision, closest practical low-footprint precision pair: BF16 safetensors versus Q2_K GGUF",
+    "gguf_quant": "Q2_K",
+    "gguf_repo": "second-state/DeepSeek-V2-Lite-Chat-GGUF",
+    "gguf_size_gb": 6.43,
+    "name": "DeepSeek-V2-Lite-Chat",
+    "rationale": "Smallest DeepSeek-family benchmark anchor that still points toward DeepSeek-V4-Flash; keeps the runtime on the DeepSeek2 path instead of falling back to a tiny but architecture-mismatched smoke model.",
+    "safetensors_precision": "bfloat16",
+    "safetensors_repo": "deepseek-ai/DeepSeek-V2-Lite-Chat"
+  },
+  "notes": [
+    "Real model execution stays opt-in and must keep model artifacts on the mounted drive.",
+    "Use the tiny fallback only for loader plumbing smoke tests; it does not replace the architecture-aligned baseline."
+  ],
+  "schema_version": 1,
+  "stop_condition": "Stop if GGUF does not provide a meaningful speed or fit benefit over the safetensors baseline for the chosen DeepSeek-family model target.",
+  "story_id": "DGR-001"
+}
--- a/.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md
+++ b/.scratch/distributed-gguf-runtime/issues/01-lock-the-safetensors-versus-gguf-performance-contract.md
@@ -13,6 +13,15 @@ Status: ready-for-agent

 As a runtime engineer, I need a controlled baseline so that GGUF work proceeds from measured speed, memory, and quality rather than reputation.

+## Baseline model target
+
+Use the same model on both sides of the comparison, with the closest practical low-footprint precision pair:
+
+- **safetensors:** `deepseek-ai/DeepSeek-V2-Lite-Chat` in **BF16**
+- **GGUF:** `second-state/DeepSeek-V2-Lite-Chat-GGUF` in **Q2_K** (~6.5GB)
+
+Keep the benchmark matrix explicit for **CPU** and **GPU** runs. Reserve smaller non-DeepSeek fallback models only for loader plumbing smoke tests if needed; they do not count as the DGR-001 architecture-aligned baseline.
+
 ## Expected durable outputs

 - Benchmark harness and deterministic tests
--- a/.scratch/distributed-inference-performance/prd.json
+++ b/.scratch/distributed-inference-performance/prd.json
@@ -16,8 +16,9 @@
      ],
      "priority": 1,
      "passes": true,
-      "notes": "Completed 2026-07-14. Deterministic direct/relay and cached/stateless stub benchmark with JSON/summary attribution; focused test suite passes (7). Source issue: .scratch/distributed-inference-performance/issues/01-baseline-profiling-harness.md",
-      "dependsOn": []
+      "notes": "Source issue: .scratch/distributed-inference-performance/issues/01-baseline-profiling-harness.md",
+      "dependsOn": [],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-002",
@@ -31,9 +32,12 @@
        "Tests cover binary, JSON, timeout, disconnect, cancellation, and cleanup"
      ],
      "priority": 2,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/02-relay-session-compatibility.md",
-      "dependsOn": ["DIP-001"]
+      "dependsOn": [
+        "DIP-001"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-003",
@@ -47,9 +51,12 @@
        "Benchmark shows healthy-session connection count independent of token count"
      ],
      "priority": 3,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/03-http-keepalive.md",
-      "dependsOn": ["DIP-001"]
+      "dependsOn": [
+        "DIP-001"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-004",
@@ -63,9 +70,12 @@
        "Tests verify cadence and cleanup"
      ],
      "priority": 4,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/04-seam-telemetry.md",
-      "dependsOn": ["DIP-001"]
+      "dependsOn": [
+        "DIP-001"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-005",
@@ -79,9 +89,12 @@
        "Tests cover compressible, incompressible, threshold, malformed, and legacy bodies"
      ],
      "priority": 5,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/05-adaptive-compression.md",
-      "dependsOn": ["DIP-001"]
+      "dependsOn": [
+        "DIP-001"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-006",
@@ -95,9 +108,12 @@
        "Wire and token-output regression tests pass"
      ],
      "priority": 6,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/06-activation-framing-copies.md",
-      "dependsOn": ["DIP-001"]
+      "dependsOn": [
+        "DIP-001"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-007",
@@ -111,9 +127,13 @@
        "Tests cover chunking, slow consumers, failure, and legacy peers"
      ],
      "priority": 7,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/07-prefill-backpressure.md",
-      "dependsOn": ["DIP-001", "DIP-004"]
+      "dependsOn": [
+        "DIP-001",
+        "DIP-004"
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "DIP-008",
@@ -127,9 +147,20 @@
        "Gate verifies token identity, session stability, and resource cleanup"
      ],
      "priority": 8,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/distributed-inference-performance/issues/08-end-to-end-performance-gate.md",
-      "dependsOn": ["DIP-002", "DIP-003", "DIP-004", "DIP-005", "DIP-006", "DIP-007"]
+      "dependsOn": [
+        "DIP-002",
+        "DIP-003",
+        "DIP-004",
+        "DIP-005",
+        "DIP-006",
+        "DIP-007"
+      ],
+      "completionNotes": "Completed by agent"
    }
-  ]
+  ],
+  "metadata": {
+    "updatedAt": "2026-07-12T02:35:28.752Z"
+  }
 }
--- a/.scratch/node-capability-admission/prd.json
+++ b/.scratch/node-capability-admission/prd.json
@@ -35,11 +35,12 @@
        "Full pytest passes or an exact unrelated blocker is recorded"
      ],
      "priority": 2,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/node-capability-admission/issues/02-doctor-real-forward.md",
      "dependsOn": [
        "NCA-001"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "NCA-003",
@@ -54,12 +55,13 @@
        "Full pytest passes or an exact unrelated blocker is recorded"
      ],
      "priority": 3,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/node-capability-admission/issues/03-fail-closed-startup-admission.md",
      "dependsOn": [
        "NCA-001",
        "NCA-002"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "NCA-004",
@@ -76,12 +78,13 @@
        "Full pytest passes or an exact unrelated blocker is recorded"
      ],
      "priority": 4,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/node-capability-admission/issues/04-tracker-validated-capability-routing.md",
      "dependsOn": [
        "NCA-001",
        "NCA-003"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
    },
    {
      "id": "NCA-005",
@@ -96,15 +99,16 @@
        "Full pytest passes or an exact unrelated blocker is recorded"
      ],
      "priority": 5,
-      "passes": false,
+      "passes": true,
      "notes": "Source issue: .scratch/node-capability-admission/issues/05-docs-hardware-lane-contract.md",
      "dependsOn": [
        "NCA-002",
        "NCA-004"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
    }
  ],
  "metadata": {
-    "updatedAt": "2026-07-11T19:16:52.768Z"
+    "updatedAt": "2026-07-12T01:54:03.030Z"
  }
 }
--- a/docs/issues/42-gguf-llamacpp-node-backend.md
+++ b/docs/issues/42-gguf-llamacpp-node-backend.md
@@ -1,9 +1,16 @@
 # US-042 — GGUF/llama.cpp node backend

 Status: planned
-Priority: High (whole-model GGUF shortcut; distributed path in [ADR-0024](../adr/0024-distributed-gguf-runtime.md))
+Priority: High (unlocks DeepSeek-V4-Flash on volunteer hardware — the pool's core value)
 Stage: Draft design

+## Goal
+
+Run **DeepSeek-V4-Flash** as the first real large-model target on volunteer
+hardware via GGUF/llama.cpp. This epic is no longer GLM-oriented: the initial
+objective is to prove that DeepSeek-V4-Flash can load and serve correctly on
+consumer/unified-memory nodes, then expand from there.
+
 ## Context

 The node backend is transformers-only (`model_backend.py` →
@@ -35,17 +42,7 @@ to it (single-hop route). Smallest step, no cross-node activation work, and
 already useful: Strix Halo 128 GB serves DeepSeek-V4-Flash IQ3_XXS (114 GB)
 via llama.cpp Vulkan today.

-Recommended sequencing: **C first** (US-042), then **ADR-0024 benchmark gate** (DGR-001), then distributed native worker (DGR-002+). Direction B (llama.cpp RPC) is rejected per ADR-0024.
-
-## Runtime sequencing
-
-| Stage | Track | Delivers |
-|---|---|---|
-| **C — Whole-model GGUF** | US-042 (this issue) | Single-hop llama.cpp, billing, relay streaming |
-| **0 — Benchmark gate** | ADR-0024 DGR-001 | Safetensors vs GGUF measured contract |
-| **1 — Distributed GGUF** | ADR-0024 `.scratch/distributed-gguf-runtime/` | gRPC C++ worker, layer-range GGUF |
-
-Phase C uses the existing tracker hop path (whole model, one node). ADR-0024 direction A (layer-range GGUF + activations) merges into the native worker track after the benchmark gate — not in parallel with phase C on the same backend without an integration plan.
+Recommended sequencing: C first (small, real value), then A/B investigation.

 ## Also in scope

--- a/packages/node/meshnet_node/performance_contract.py
+++ b/packages/node/meshnet_node/performance_contract.py
@@ -0,0 +1,188 @@
+"""Versioned performance contract metadata for DGR-001.
+
+This module intentionally captures the *contract* first: the model family,
+architecture alignment, benchmark lanes, and stop condition that later benchmark
+runs must satisfy. It does not download or execute a model.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+CONTRACT_ID = "DGR-001"
+DEFAULT_OUTPUT_PATH = Path(".scratch/distributed-gguf-runtime/evidence/DGR-001/performance-contract.json")
+
+
+@dataclass(frozen=True)
+class ModelTarget:
+    """Architecture-aligned model target for the DGR-001 benchmark contract."""
+
+    name: str
+    architecture: str
+    safetensors_repo: str
+    safetensors_precision: str
+    gguf_repo: str
+    gguf_quant: str
+    gguf_size_gb: float
+    comparison_policy: str
+    rationale: str
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "architecture": self.architecture,
+            "safetensors_repo": self.safetensors_repo,
+            "safetensors_precision": self.safetensors_precision,
+            "gguf_repo": self.gguf_repo,
+            "gguf_quant": self.gguf_quant,
+            "gguf_size_gb": self.gguf_size_gb,
+            "comparison_policy": self.comparison_policy,
+            "rationale": self.rationale,
+        }
+
+
+@dataclass(frozen=True)
+class BenchmarkLane:
+    """One side of the comparison the contract requires."""
+
+    id: str
+    runtime: str
+    device: str
+    recipe: str
+    concurrency_levels: tuple[int, ...]
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "runtime": self.runtime,
+            "device": self.device,
+            "recipe": self.recipe,
+            "concurrency_levels": list(self.concurrency_levels),
+        }
+
+
+@dataclass(frozen=True)
+class PerformanceContract:
+    """Machine-readable contract for the DGR-001 benchmark story."""
+
+    schema_version: int
+    story_id: str
+    model_target: ModelTarget
+    benchmark_lanes: tuple[BenchmarkLane, ...]
+    metrics: tuple[str, ...]
+    stop_condition: str
+    notes: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "story_id": self.story_id,
+            "model_target": self.model_target.to_dict(),
+            "benchmark_lanes": [lane.to_dict() for lane in self.benchmark_lanes],
+            "metrics": list(self.metrics),
+            "stop_condition": self.stop_condition,
+            "notes": list(self.notes),
+        }
+
+    def write_json(self, path: str | Path) -> Path:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.to_dict(), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        return path
+
+
+DEFAULT_CONTRACT = PerformanceContract(
+    schema_version=SCHEMA_VERSION,
+    story_id=CONTRACT_ID,
+    model_target=ModelTarget(
+        name="DeepSeek-V2-Lite-Chat",
+        architecture="deepseek2",
+        safetensors_repo="deepseek-ai/DeepSeek-V2-Lite-Chat",
+        safetensors_precision="bfloat16",
+        gguf_repo="second-state/DeepSeek-V2-Lite-Chat-GGUF",
+        gguf_quant="Q2_K",
+        gguf_size_gb=6.43,
+        comparison_policy=(
+            "same model/revision, closest practical low-footprint precision pair: "
+            "BF16 safetensors versus Q2_K GGUF"
+        ),
+        rationale=(
+            "Smallest DeepSeek-family benchmark anchor that still points toward "
+            "DeepSeek-V4-Flash; keeps the runtime on the DeepSeek2 path instead "
+            "of falling back to a tiny but architecture-mismatched smoke model."
+        ),
+    ),
+    benchmark_lanes=(
+        BenchmarkLane(
+            id="transformers-safetensors-cpu",
+            runtime="transformers",
+            device="cpu",
+            recipe="current safetensors recipe",
+            concurrency_levels=(1, 4),
+        ),
+        BenchmarkLane(
+            id="llama-cpp-gguf-cpu",
+            runtime="llama.cpp",
+            device="cpu",
+            recipe="whole-model GGUF recipe",
+            concurrency_levels=(1, 4),
+        ),
+        BenchmarkLane(
+            id="transformers-safetensors-gpu",
+            runtime="transformers",
+            device="gpu",
+            recipe="current safetensors recipe",
+            concurrency_levels=(1, 4),
+        ),
+        BenchmarkLane(
+            id="llama-cpp-gguf-gpu",
+            runtime="llama.cpp",
+            device="gpu",
+            recipe="whole-model GGUF recipe",
+            concurrency_levels=(1, 4),
+        ),
+    ),
+    metrics=(
+        "ttft_ms",
+        "prefill_tok_per_sec",
+        "decode_tok_per_sec",
+        "p50_latency_ms",
+        "p95_latency_ms",
+        "aggregate_throughput_tok_per_sec",
+        "rss_bytes",
+        "vram_bytes",
+        "artifact_bytes",
+        "failure_count",
+        "output_drift",
+    ),
+    stop_condition=(
+        "Stop if GGUF does not provide a meaningful speed or fit benefit over the "
+        "safetensors baseline for the chosen DeepSeek-family model target."
+    ),
+    notes=(
+        "Real model execution stays opt-in and must keep model artifacts on the mounted drive.",
+        "Use the tiny fallback only for loader plumbing smoke tests; it does not replace the architecture-aligned baseline.",
+    ),
+)
+
+
+def build_default_contract() -> PerformanceContract:
+    return DEFAULT_CONTRACT
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Write the DGR-001 performance contract JSON")
+    parser.add_argument("--json-out", type=Path, default=DEFAULT_OUTPUT_PATH, help="output JSON path")
+    args = parser.parse_args(argv)
+    contract = build_default_contract()
+    path = contract.write_json(args.json_out)
+    print(path)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry point
+    raise SystemExit(main())
--- a/packages/node/meshnet_node/torch_server.py
+++ b/packages/node/meshnet_node/torch_server.py
@@ -1545,6 +1545,26 @@ class TorchNodeServer:

    def apply_tracker_directives(self, directives: list[dict]) -> dict | None:
        """Apply tracker shard directives (LOAD_SHARD replace, ADD_SHARD load-more)."""
+        drop_directive = next(
+            (directive for directive in reversed(directives) if directive.get("action") == "DROP_SHARD"),
+            None,
+        )
+        if drop_directive is not None:
+            model_id = str(drop_directive.get("model") or "")
+            removed = self._backends.pop(model_id, None)
+            if removed is None:
+                return None
+            if self._backends:
+                self._backend = next(iter(self._backends.values()))
+                self._tracker_mode = self._backend.shard_start == 0
+            else:
+                self._backend = None
+                self._tracker_mode = False
+            if self._server is not None:
+                self._server.backends = dict(self._backends)
+                self._server.backend = self._backend
+                self._server.tracker_mode = self._tracker_mode
+            return {"action": "DROP_SHARD", "model": model_id}
        add_directive = next(
            (directive for directive in reversed(directives) if directive.get("action") == "ADD_SHARD"),
            None,
@@ -1574,6 +1594,8 @@ class TorchNodeServer:
            flush=True,
        )
        try:
+            if replacing:
+                self._backends.clear()
            new_backend = _load_backend(model_id, shard_start, shard_end, quantization, self._cache_dir)
        except TypeError:
            new_backend = _load_backend(model_id, shard_start, shard_end, quantization)
--- a/packages/tracker/meshnet_tracker/dashboard.html
+++ b/packages/tracker/meshnet_tracker/dashboard.html
@@ -22,8 +22,9 @@
           border-bottom:1px solid var(--border); flex-shrink:0; }
  header h1 { font-size:16px; margin:0; color:var(--accent); }
  header .meta { color:var(--dim); font-size:12px; }
-  main { display:grid; grid-template-columns:repeat(auto-fit,minmax(340px,1fr));
+  main { display:grid; grid-template-columns:1fr;
          gap:14px; padding:14px 20px; }
+  main > section { width:100%; min-width:0; }
  body.chat-tab-active main {
    flex:1; min-height:0; display:flex; flex-direction:column;
    padding:0; gap:0; overflow:hidden;
@@ -71,6 +72,12 @@
          background:transparent; color:var(--dim); padding:5px 0 8px; }
  .dashboard-tabs button.active { color:var(--accent); border-bottom-color:var(--accent); }
  .wide { grid-column:1 / -1; }
+  /* Compact status cards fan out on desktop; tables remain readable at half width. */
+  @media (min-width:900px) {
+    main { grid-template-columns:repeat(4,minmax(0,1fr)); }
+    main > section { grid-column:span 1; }
+    .wide { grid-column:span 2; }
+  }
  section[hidden] { display:none !important; }
  section.chat-section {
    padding:0; border:0; border-radius:0; background:var(--bg); min-height:0;
@@ -288,6 +295,7 @@
  <section data-tab="billing" data-admin-only><h2>Node pending payouts</h2><div id="pending" class="empty">admin login required</div></section>
  <section data-tab="billing" data-admin-only><h2>Settlement history</h2><div id="settlements" class="empty">admin login required</div></section>
  <section data-tab="admin"><h2>Tracker hive</h2><div id="hive" class="empty">loading…</div></section>
+  <section data-tab="admin" class="wide"><h2>Model placement</h2><div id="admin-model-placement-status" class="dim">Choose a model to load or release.</div><div id="admin-model-placement" class="empty">admin login required</div></section>
  <section data-tab="admin" id="admin-section"><h2>All accounts (admin)</h2><div id="admin" class="empty"></div></section>
  <section data-tab="admin" data-admin-only><h2>Strikes / bans / forfeitures</h2><div id="fraud" class="empty">admin login required</div></section>
  <section data-tab="admin"><h2>Client balances</h2><div id="clients" class="empty">admin login required</div></section>
@@ -1791,6 +1799,50 @@ async function requestSelectedModelLoad() {
  $("chat-status").textContent = `load queued on ${short(assignment.node_id || "node")} for layers ${assignment.shard_start}-${assignment.shard_end}`;
 }

+async function requestAdminModelLoad(model) {
+  const result = await apiCall("/v1/models/load", "POST", { model, force: true });
+  if (!result.ok) return showAdminModelPlacementStatus(result.data.error || "model load request failed", true);
+  const assignment = result.data.assignment || {};
+  showAdminModelPlacementStatus(`Load queued on ${short(assignment.node_id || "node")} for ${model}.`);
+  await refreshActiveTab(true);
+}
+
+async function releaseAdminModel(model) {
+  const result = await apiCall("/v1/models/release", "POST", { model });
+  if (!result.ok) return showAdminModelPlacementStatus(result.data.error || "model release request failed", true);
+  showAdminModelPlacementStatus(`Release queued for ${result.data.released || 0} node(s) serving ${model}.`);
+  await refreshActiveTab(true);
+}
+
+function showAdminModelPlacementStatus(message, isError) {
+  const status = $("admin-model-placement-status");
+  status.textContent = message;
+  status.className = isError ? "bad" : "ok";
+}
+
+function renderAdminModelPlacement(models, map) {
+  const nodes = (map && map.nodes) || [];
+  const rows = ((models && models.data) || []).map(model => {
+    const aliases = new Set([model.id, model.hf_repo, ...(model.aliases || [])].filter(Boolean));
+    const serving = nodes.filter(node => aliases.has(node.model) || aliases.has(node.hf_repo)).length;
+    const downloaded = nodes.filter(node => aliases.has(node.model) || aliases.has(node.hf_repo) ||
+      (node.downloaded_models || []).some(item => aliases.has(item.model) || aliases.has(item.hf_repo))).length;
+    const actions = `<button class="small" data-admin-model-load="${esc(model.id)}">load</button> ` +
+      `<button class="small" data-admin-model-release="${esc(model.id)}"${serving ? "" : " disabled"}>release</button>`;
+    return [esc(model.name || model.id), String(serving), String(downloaded), actions];
+  });
+  $("admin-model-placement").innerHTML = rows.length
+    ? table(["model", "serving nodes", "downloaded on nodes", "admin action"], rows)
+    : '<div class="empty">no model presets configured</div>';
+}
+
+$("admin-model-placement").addEventListener("click", event => {
+  const load = event.target.closest("[data-admin-model-load]");
+  const release = event.target.closest("[data-admin-model-release]");
+  if (load) void requestAdminModelLoad(load.dataset.adminModelLoad);
+  if (release) void releaseAdminModel(release.dataset.adminModelRelease);
+});
+
 function chatAuthToken() {
  if (accountApiKeys.length) return accountApiKeys[0];
  return null;
@@ -2427,14 +2479,17 @@ async function fetchAdminTab() {
    fetchJson("/v1/console"),
    fetchJson("/v1/billing/summary"),
    fetchJson("/v1/registry/wallets"),
+    fetchJson("/v1/models"),
+    fetchJson("/v1/network/map"),
  ];
  if (isAdmin) fetches.push(apiCall("/v1/admin/accounts"));
  const results = await Promise.all(fetches);
-  const [raft, consoleData, summary, wallets, adminResp] = results;
+  const [raft, consoleData, summary, wallets, models, map, adminResp] = results;
  renderIfChanged("hive", raft, renderHive);
  renderIfChanged("console", consoleData, renderConsole);
  renderIfChanged("billing-summary", summary, data => renderBilling(data));
  renderIfChanged("fraud", { wallets, summary }, data => renderFraud(data.wallets, data.summary));
+  renderIfChanged("admin-model-placement", { models, map }, data => renderAdminModelPlacement(data.models, data.map));
  if (adminResp && adminResp.ok) {
    renderIfChanged("admin", adminResp.data.accounts || [], accounts => {
      const rows = accounts.map(a => {
--- a/packages/tracker/meshnet_tracker/server.py
+++ b/packages/tracker/meshnet_tracker/server.py
@@ -1528,6 +1528,49 @@ def _request_model_load_locked(server: "_TrackerHTTPServer", model_key: str) ->
    return None


+def _force_model_load_locked(server: "_TrackerHTTPServer", model_key: str) -> dict | None:
+    """Replace the fastest ready assignment after an explicit admin eviction."""
+    resolved_name, preset = _resolve_model_preset(server.model_presets, model_key)
+    if preset is None or not preset.get("hf_repo"):
+        return None
+    start, end = _preset_layer_bounds(preset)
+    candidates = [node for node in server.registry.values()
+                  if node.status == "ready" and node.pending_new_assignment is None
+                  and _has_usable_quantization(node)]
+    if not candidates:
+        return None
+    node = max(candidates, key=lambda item: item.benchmark_tokens_per_sec)
+    shard_end = min(end, start + min(_node_layer_capacity(node, preset), end - start + 1) - 1)
+    if shard_end < start:
+        return None
+    quantization = _node_quantization(node, preset)
+    directive = _load_directive(node, str(preset["hf_repo"]), start, shard_end, quantization)
+    replaced = node.hf_repo or node.model
+    node.model, node.hf_repo = resolved_name, str(preset["hf_repo"])
+    node.shard_start, node.shard_end, node.quantization = start, shard_end, quantization
+    node.managed_assignment, node.pending_new_assignment = True, directive
+    node.pending_directives.append(directive)
+    _tracker_log(server, "warn", "model load forced", node_id=node.node_id,
+                 model=resolved_name, replaced_model=replaced, shard=f"{start}-{shard_end}")
+    return {"node_id": node.node_id, "model": resolved_name, "hf_repo": preset["hf_repo"],
+            "shard_start": start, "shard_end": shard_end, "replaced_model": replaced}
+
+
+def _release_model_locked(server: "_TrackerHTTPServer", model_key: str) -> int:
+    """Queue DROP_SHARD for every served shard and remove it from routing immediately."""
+    resolved_name, preset = _resolve_model_preset(server.model_presets, model_key)
+    if preset is None:
+        return 0
+    released = 0
+    for node in server.registry.values():
+        if not _node_matches_preset(node, resolved_name, preset) or node.shard_start is None or node.shard_end is None:
+            continue
+        node.pending_directives.append(_drop_directive(node, str(preset.get("hf_repo") or resolved_name), node.shard_start, node.shard_end, node.quantization or "bfloat16"))
+        node.status = "loading"
+        released += 1
+    return released
+
+
 def _preferred_node_quantization(
    node: _NodeEntry,
    preset: dict,
@@ -3043,6 +3086,9 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
        if self.path == "/v1/models/load":
            self._handle_model_load_request()
            return
+        if self.path == "/v1/models/release":
+            self._handle_model_release_request()
+            return
        if self.path == "/v1/models/vote":
            self._handle_model_coverage_vote()
            return
@@ -3170,8 +3216,6 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
        seen_ids: set[str] = set()
        for name, preset in server.model_presets.items():
            model_nodes = [node for node in alive if _node_matches_preset(node, name, preset)]
-            if not model_nodes and not preset.get("recommended"):
-                continue
            required_start, required_end = _preset_layer_bounds(preset)
            coverage = _coverage_percentage(
                model_nodes,
@@ -4834,11 +4878,32 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
        with server.lock:
            self._purge_expired_nodes()
            assignment = _request_model_load_locked(server, model)
+            if assignment is None and body.get("force") is True:
+                assignment = _force_model_load_locked(server, model)
        if assignment is None:
            self._send_json(409, {"error": "no ready joined node has an available model slot and sufficient capacity"})
            return
        self._send_json(202, {"status": "queued", "assignment": assignment})

+    def _handle_model_release_request(self):
+        server: _TrackerHTTPServer = self.server  # type: ignore[assignment]
+        if not self._require_role("admin", "validator"):
+            return
+        body = self._read_json_body()
+        if body is None:
+            return
+        model = body.get("model")
+        if not isinstance(model, str) or not model.strip():
+            self._send_json(400, {"error": "model is required"})
+            return
+        with server.lock:
+            self._purge_expired_nodes()
+            released = _release_model_locked(server, model)
+        if not released:
+            self._send_json(404, {"error": "no served shards found for model"})
+            return
+        self._send_json(202, {"status": "release_queued", "released": released})
+
    def _handle_model_coverage_vote(self):
        """Record a rolling wish-list signal for an unavailable precision."""
        server: _TrackerHTTPServer = self.server  # type: ignore[assignment]
--- a/tests/test_dashboard.py
+++ b/tests/test_dashboard.py
@@ -39,7 +39,9 @@ def test_dashboard_served_with_all_panels():
        assert "resolveModelGroup" in html
        assert "buildModelAliasMap" in html
        assert "modelAliasKey(raw)" in html
-        assert "main { display:grid; grid-template-columns:repeat(auto-fit,minmax(340px,1fr));" in html
+        assert "@media (min-width:900px)" in html
+        assert "grid-template-columns:repeat(4,minmax(0,1fr));" in html
+        assert ".wide { grid-column:span 2; }" in html
        assert 'onclick="clearConsole()"' in html
        assert "let consoleClearedAt = 0;" in html
    finally:
@@ -100,6 +102,20 @@ def test_dashboard_allows_admin_to_request_selected_model_load():
    assert '$("request-model-load").style.display = enabled ? "" : "none"' in html


+def test_dashboard_exposes_admin_model_inventory_and_release_controls():
+    "Admin placement controls show the full model inventory and can release capacity."
+    html = _dashboard_html()
+
+    assert 'id="admin-model-placement"' in html
+    assert "renderAdminModelPlacement" in html
+    assert '"/v1/models/release"' in html
+    assert "requestAdminModelLoad" in html
+    assert "releaseAdminModel" in html
+    assert 'data-admin-model-load=' in html
+    assert 'data-admin-model-release=' in html
+    assert "admin-model-placement-status" in html
+
+
 def test_network_map_includes_node_friendly_name():
    "Network map includes node friendly name\n\nTags: dashboard, http"
    tracker = TrackerServer()
--- a/tests/test_dynamic_routing.py
+++ b/tests/test_dynamic_routing.py
@@ -355,6 +355,39 @@ def test_admin_model_load_request_queues_directive_on_joined_node():
    assert heartbeat["directives"][0]["model"] == "Qwen/Qwen2.5-0.5B-Instruct"


+def test_admin_can_replace_a_served_model_and_release_it():
+    "Forced admin placement replaces a served shard; release queues DROP_SHARD."
+    tracker = TrackerServer(enable_billing=False, validator_service_token="test-admin")
+    port = tracker.start()
+    try:
+        node = _post_json(
+            f"http://127.0.0.1:{port}/v1/nodes/register",
+            {"endpoint": "http://127.0.0.1:9912", "model": "stub-model",
+             "shard_start": 0, "shard_end": 3, "managed_assignment": True,
+             "max_loaded_shards": 1, "memory_mb": 1,
+             "hardware_profile": {"host_id": "full-host"}},
+        )
+        headers = {"Content-Type": "application/json", "Authorization": "Bearer test-admin"}
+        load = urllib.request.Request(
+            f"http://127.0.0.1:{port}/v1/models/load",
+            data=json.dumps({"model": "qwen2.5-0.5b-instruct", "force": True}).encode(),
+            headers=headers, method="POST")
+        with urllib.request.urlopen(load) as response:
+            assert json.loads(response.read())["assignment"]["node_id"] == node["node_id"]
+        heartbeat = _post_json(f"http://127.0.0.1:{port}/v1/nodes/{node['node_id']}/heartbeat", {})
+        assert heartbeat["directives"][0]["action"] == "LOAD_SHARD"
+        release = urllib.request.Request(
+            f"http://127.0.0.1:{port}/v1/models/release",
+            data=json.dumps({"model": "qwen2.5-0.5b-instruct"}).encode(), headers=headers, method="POST")
+        with urllib.request.urlopen(release) as response:
+            assert json.loads(response.read())["released"] == 1
+        heartbeat = _post_json(f"http://127.0.0.1:{port}/v1/nodes/{node['node_id']}/heartbeat", {})
+    finally:
+        tracker.stop()
+
+    assert heartbeat["directives"][0]["action"] == "DROP_SHARD"
+
+
 def test_endpoint_key_distinguishes_same_port_different_hosts():
    "Endpoint key distinguishes same port different hosts\n\nTags: http, performance, routing, tracker"
    from meshnet_node.torch_server import _clamp_downstream_hops, _endpoint_key
--- a/tests/test_performance_contract.py
+++ b/tests/test_performance_contract.py
@@ -0,0 +1,84 @@
+"""Tests for the DGR-001 performance contract metadata."""
+
+from __future__ import annotations
+
+import json
+
+from meshnet_node.performance_contract import DEFAULT_CONTRACT, SCHEMA_VERSION, main
+
+
+def test_default_contract_is_architecture_aligned_and_small():
+    """The baseline stays on DeepSeek2 and uses the smallest DeepSeek-family GGUF.
+
+    Tags: performance, model, gguf
+    """
+    payload = DEFAULT_CONTRACT.to_dict()
+
+    assert payload["schema_version"] == SCHEMA_VERSION
+    assert payload["story_id"] == "DGR-001"
+    assert payload["model_target"] == {
+        "name": "DeepSeek-V2-Lite-Chat",
+        "architecture": "deepseek2",
+        "safetensors_repo": "deepseek-ai/DeepSeek-V2-Lite-Chat",
+        "safetensors_precision": "bfloat16",
+        "gguf_repo": "second-state/DeepSeek-V2-Lite-Chat-GGUF",
+        "gguf_quant": "Q2_K",
+        "gguf_size_gb": 6.43,
+        "comparison_policy": (
+            "same model/revision, closest practical low-footprint precision pair: "
+            "BF16 safetensors versus Q2_K GGUF"
+        ),
+        "rationale": (
+            "Smallest DeepSeek-family benchmark anchor that still points toward "
+            "DeepSeek-V4-Flash; keeps the runtime on the DeepSeek2 path instead "
+            "of falling back to a tiny but architecture-mismatched smoke model."
+        ),
+    }
+    assert payload["benchmark_lanes"] == [
+        {
+            "id": "transformers-safetensors-cpu",
+            "runtime": "transformers",
+            "device": "cpu",
+            "recipe": "current safetensors recipe",
+            "concurrency_levels": [1, 4],
+        },
+        {
+            "id": "llama-cpp-gguf-cpu",
+            "runtime": "llama.cpp",
+            "device": "cpu",
+            "recipe": "whole-model GGUF recipe",
+            "concurrency_levels": [1, 4],
+        },
+        {
+            "id": "transformers-safetensors-gpu",
+            "runtime": "transformers",
+            "device": "gpu",
+            "recipe": "current safetensors recipe",
+            "concurrency_levels": [1, 4],
+        },
+        {
+            "id": "llama-cpp-gguf-gpu",
+            "runtime": "llama.cpp",
+            "device": "gpu",
+            "recipe": "whole-model GGUF recipe",
+            "concurrency_levels": [1, 4],
+        },
+    ]
+    assert "ttft_ms" in payload["metrics"]
+    assert "output_drift" in payload["metrics"]
+    assert "meaningful speed or fit benefit" in payload["stop_condition"]
+    assert any("mounted drive" in note for note in payload["notes"])
+
+
+def test_contract_cli_writes_json(tmp_path, capsys):
+    """The contract can be emitted as a machine-readable artifact.
+
+    Tags: performance, artifact
+    """
+    output = tmp_path / "performance-contract.json"
+
+    assert main(["--json-out", str(output)]) == 0
+    written = json.loads(output.read_text(encoding="utf-8"))
+
+    assert written == DEFAULT_CONTRACT.to_dict()
+    assert str(output) in capsys.readouterr().out
Author	SHA1	Message	Date
Dobromir Popov	5b33bf8b99	feat: compare safetensors and gguf on cpu and gpu	2026-07-14 18:45:12 +03:00
Dobromir Popov	c7554ef7d8	feat: add DGR-001 performance contract	2026-07-14 18:13:54 +03:00
Dobromir Popov	7b3399760e	chore: wrap up completed story metadata	2026-07-14 17:09:04 +03:00
Dobromir Popov	22467f145c	merge: distributed performance baseline benchmark	2026-07-14 17:01:08 +03:00
Dobromir Popov	35af1e21de	fix: make model placement controls observable	2026-07-14 16:00:37 +02:00
Dobromir Popov	348b003d6e	fix: restore responsive dashboard panel grid	2026-07-14 15:55:24 +02:00
Dobromir Popov	1e64a5b2b9	new dash update	2026-07-14 15:29:11 +02:00
Dobromir Popov	e2f3ae32b8	feat: let admins manage model placement	2026-07-14 15:16:23 +02:00