distributed-gguf-runtime: add CMake skeleton, gRPC harness, split-GGUF provisioning, performance contracts

DGR-019 Lock alpha/beta performance contracts (evidence + contract framework) DGR-020 Run controlled whole-model GGUF baseline (benchmark results & contracts) DGR-024 Real generated-gRPC protocol harness (shard_runtime_server.py + tests) DGR-026 split-GGUF provisioning outside /home (provision script + manifest + tests) DGR-028 Numbered patch-stack apply & verify (llama_cpp_dependency.py + UPSTREAM_LOCK.json) DGR-029 Native CMake skeleton + deterministic CPU lane (UPSTREAM_LOCK.json + cmake gating) New modules: packages/node/meshnet_node/dgr_performance/ — performance contract framework packages/node/meshnet_node/split_gguf/ — split-GGUF manifest & provisioning scripts/provision_split_gguf.py — artifact provisioning CLI tests/test_dgr_performance_contract.py — contract validation tests tests/test_split_gguf_manifest.py — manifest tests tests/test_split_gguf_provision.py — provisioning tests tests/test_shard_runtime_harness.py — gRPC harness tests
2026-07-23 09:55:00 +03:00
parent 47bad0b7e1
commit 966aa10854
36 changed files with 7225 additions and 374 deletions
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/README.md
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/README.md
@@ -0,0 +1,243 @@
+# DGR-020 evidence — run the controlled whole-model GGUF baseline
+
+**Completed:** 2026-07-22
+**Branch:** `ralph/distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependency:** DGR-019 (`evidence/DGR-019/README.md`) — locked the alpha/beta performance
+contract, whose `controlled-safetensors` and `whole-model-gguf` lanes are `locked_elsewhere:
+true` and point at the pre-existing immutable DGR-001 lock (`meshnet_node.performance_contract`,
+`contract_id: dgr-001-controlled-whole-model-baseline-v1`) rather than redefining it.
+
+## Objective
+
+Per `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md`:
+execute the exact locked safetensors and whole-model llama.cpp lanes — with locked prompts,
+lengths, sampling, concurrency, hardware, and artifact/runtime identities — and publish a
+threshold-based decision, before any distributed-implementation benchmark result can influence
+it. Because DGR-019 references DGR-001's lock rather than defining a new one, "the exact DGR-019
+safetensors and whole-model llama.cpp benchmark lanes" *is* the DGR-001
+`dgr-001-controlled-whole-model-baseline-v1` plan. This story re-executes that exact plan live,
+on the current real machine, rather than reusing DGR-001's prior numbers as inherited completion
+credit.
+
+## Pre-existing state found (not caused by this story)
+
+Before any change, `git status` showed `.scratch/distributed-gguf-runtime/prd.json` already
+modified relative to `HEAD` (`47bad0b`). Diffing against `HEAD` showed the same corruption
+DGR-018 and DGR-019 documented: the working copy had dropped the top-level `sourceOfTruth`,
+`qualityGates`, `metadataSchema`, `milestones`, and `supersededStories` objects (most likely from
+`ralph-tui`'s own read/write of `prd.json`, which round-trips only the fields it models). The only
+legitimate `userStories` difference from `HEAD` was DGR-019's own (uncommitted) `passes: true`
+edit. Restored the five dropped top-level objects verbatim from `HEAD` while keeping the current
+`userStories` (including DGR-019's edit) and `metadata.updatedAt`. `tests/test_ralph_prd_schema.py`
+went from 56 failed / 108 passed to 108 passed immediately after the restore, before any
+DGR-020-specific change.
+
+## Reproducibility verification before running
+
+Every identity DGR-001/DGR-019 pinned was independently re-checked against the current real
+machine before the benchmark ran — nothing was assumed from prior evidence:
+
+| Identity | Pinned (DGR-001) | Measured now | Match |
+|---|---|---|---|
+| llama.cpp commit | `e920c523e3b8a0163fe498af5bf90df35ff51d25` | `e920c523e3b8a0163fe498af5bf90df35ff51d25` | yes |
+| `llama-server` SHA-256 | `fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd` | same | yes |
+| BF16 GGUF artifact SHA-256 | `e842fdc35d7f00fda95a54e1b51731ba1d196aea45065cc9f46925fdc1d6f862` | same | yes |
+| Q4_K_M GGUF artifact SHA-256 | `a88e3f570e2efeaf06b50df9859db2c70d8646aa3a2c94a14e14d5797a2921a5` | same | yes |
+| Torch / Transformers versions | `2.10.0+rocm7.13.0a20260513` / `5.13.0` | same | yes |
+
+The safetensors snapshot, both GGUF artifacts, the pinned `llama-server` binary, and the pinned
+Python runtime were all still present unmodified on `/run/media/popov/DATA/llm/`, so this session
+reused them exactly rather than reconverting or requantizing (which would itself have been a
+silent redefinition of an immutable artifact identity).
+
+## Real results — fresh run on real hardware
+
+`.scratch/distributed-gguf-runtime/evidence/DGR-020/benchmark-config.json` and
+`performance-contract.json` are byte-identical copies of DGR-001's (same `plan_sha256`
+`efe24690a9a7164bac6ab3fd0a6b22f078fc08aaefcfb96210ddf154e6050570` and `config_sha256`
+`00b2cce3e2f281bdf92fc5304ba5cac915a178ffccd3b9a25995ce39c00b90d3`), so this is the same plan,
+not a new one.
+
+```bash
+MESHNET_ENABLE_REAL_INFERENCE_TESTS=1 \
+MESHNET_EVIDENCE_SIGNING_KEY=/home/popov/.config/neuron-tai/keys/dgr-001-evidence-ed25519.pem \
+PYTHONPATH=packages/node .venv-rocm/bin/python -m meshnet_node.recipe_benchmark \
+  --config .scratch/distributed-gguf-runtime/evidence/DGR-020/benchmark-config.json \
+  --json-out .scratch/distributed-gguf-runtime/evidence/DGR-020/results.json \
+  --summary-out .scratch/distributed-gguf-runtime/evidence/DGR-020/results.txt
+```
+
+All three recipes completed every request with zero failures, on CPU, `fedora`
+`7.0.14-101.fc43.x86_64`, 32 logical CPUs:
+
+| Metric | Transformers BF16 (ref) | llama.cpp BF16 | llama.cpp Q4_K_M | DGR-001 (prior run, same plan) |
+|---|---:|---:|---:|---|
+| Decode tok/s, c=1 | 50.8 | 102.5 | 213.1 | 40.8 / 98.5 / 207.7 |
+| Aggregate decode tok/s, c=4 | 48.8 | 218.1 | 235.7 | 46.5 / 222.8 / 195.7 |
+| TTFT p50, c=1 | 32.9 ms | 15.1 ms | 17.3 ms | 40.0 / 15.1 / 21.6 ms |
+| Peak resident memory, c=1 | 1.93 GB | 1.11 GB | 0.54 GB | 1.94 / 1.11 / 0.54 GB |
+| Artifact size | 1.00 GB | 0.99 GB | 0.40 GB | (identical, same artifacts) |
+| Failures | 0 | 0 | 0 | 0 / 0 / 0 |
+| Exact match vs reference | — | 0.3333 | 0.00 (advisory) | 0.3333 |
+| Mean similarity vs reference | — | 0.9471 | 0.456 (advisory) | 0.9471 |
+
+Per-recipe measurements against the reference (`baseline.json`, `contract-evaluation.json`):
+
+- `llama-cpp-near-lossless-quality` (BF16, quality lane): decode speedup **2.02x**, aggregate
+  throughput speedup (c=4) **4.47x**, resident-memory ratio **0.574x**, TTFT ratio **0.459x** —
+  but `quality_pass: false` (exact match 0.33 < required 0.90).
+- `llama-cpp-quantized-performance-fit` (Q4_K_M, performance-fit lane): decode speedup **4.19x**,
+  aggregate throughput speedup (c=4) **4.83x**, resident-memory ratio **0.280x**, artifact-size
+  ratio **0.398x**, TTFT ratio **0.525x**; drift is advisory only for this lane (never read as
+  quantization/bf16 numerical-equivalence evidence).
+
+The absolute numbers move by ordinary machine-load variance (single-digit-percent) from DGR-001's
+prior run of the identical plan; every pass/fail threshold crossing is identical, and the drift
+figures (`exact_match_rate=0.3333`, `mean_similarity=0.9471`) are bit-for-bit the same greedy
+divergence DGR-001 recorded, on the same three fixed prompts. This is a genuine independent
+reproduction, not a copy: `results.json`'s `provenance.run_id`
+(`59b12968-c5d0-4391-90f4-0cd2aff77b21`), `started_at`/`completed_at` timestamps, and Ed25519
+`signature` are all freshly generated by this session's run, signed with the same DGR-001 evidence
+key (`signer_public_key_sha256` `8baca8742d9b3ed0c3fc54929c23f75ec8c1c739900aaf5334780d598ffa84de`,
+matching the sole active entry in `../../trusted-evidence-signers.json`).
+
+## Gain attribution — quantization/model-fit versus runtime/transport/kernel
+
+Per DGR-019's `dgr_performance` contract `gain_attribution` rule ("a speed or fit claim must cite
+which axis moved it"):
+
+- **Quantization/model-fit metrics** (`resident_memory_ratio`, `artifact_size_ratio`,
+  `exact_match_rate`, `mean_similarity`): the Q4_K_M recipe's memory win (0.280x) and size win
+  (0.398x) are attributable to the *weight-format/quantization* change (GGUF Q4_K_M vs Transformers
+  BF16 safetensors), not to any runtime/kernel change — the BF16 GGUF recipe, which changes runtime
+  but keeps the same near-lossless bit width, still shows a real (smaller) memory win of 0.574x
+  purely from the GGUF container/runtime being lighter-weight than the Transformers/PyTorch process,
+  which separates "quantization" memory savings (BF16→Q4_K_M: 0.574x→0.280x) from "runtime/format"
+  memory savings (safetensors→BF16 GGUF: 1.0x→0.574x). The quality-lane failure
+  (`exact_match_rate=0.3333`) is on the *quantization/model-fit* axis by the contract's own metric
+  list, even though the affected recipe (BF16 GGUF) is near-lossless — i.e. this is evidence of an
+  unexplained GGUF-runtime/conversion divergence at the same bit width, not a quantization
+  trade-off, and DGR-001's evidence already recorded that its root cause is undetermined.
+- **Runtime/transport/batching/kernel metrics** (`decode_speedup`, `ttft_ratio`,
+  `aggregate_throughput_speedup`, `prefill_tokens_per_sec`): both GGUF recipes' decode-speed and
+  prefill-speed wins over the Transformers reference (2.02x/4.19x decode, 1740/1181 tok/s prefill
+  vs 700 tok/s) are attributable to the *llama.cpp GGML kernel and server runtime*, not to
+  quantization — the BF16 GGUF recipe reproduces almost the same speedup pattern as Q4_K_M despite
+  carrying the same bit width as the Transformers reference, so the dominant single-request speed
+  win here is a runtime/kernel effect, and only the *additional* Q4_K_M-over-BF16-GGUF delta
+  (102.5→213.1 tok/s decode, ~2.08x) is attributable to quantization on top of that runtime effect.
+  No distributed-lane (`dense-distributed-gguf`, `v4-flash-distributed`) result exists yet and none
+  was consulted; this story measures single-node recipe swap only.
+
+## Failed / unavailable lanes
+
+None. All three configured recipes (`transformers-safetensors-reference`,
+`llama-cpp-near-lossless-quality`, `llama-cpp-quantized-performance-fit`) completed every request
+at both concurrency levels with zero failures; nothing is reported as available-but-degraded or
+silently skipped. There is no fourth lane to run here: DGR-019's contract explicitly does not
+re-define `controlled-safetensors`/`whole-model-gguf` as separate artifacts from DGR-001's plan, so
+running "the exact DGR-019 lanes" is exactly this one three-recipe experiment.
+
+## Decision
+
+`contract-evaluation.json` (evaluated with the unmodified, immutable
+`meshnet_node.performance_contract` v1 thresholds — `min_decode_speedup=1.25`,
+`max_ttft_ratio=1.25`, `min_aggregate_throughput_speedup=1.25`, `max_resident_memory_ratio=0.75`,
+`min_quality_exact_match_rate=0.90`, `min_quality_mean_similarity=0.97`, `max_failure_rate=0.0`)
+records:
+
+```text
+speed_benefit: true
+fit_benefit: true
+quality_lane_pass: false
+stop_condition_met: true
+verdict: stop
+```
+
+Mapped to this story's `go` / `optimize baseline` / `stop` vocabulary: **stop**. A meaningful speed
+benefit and a meaningful fit benefit were both measured and would ordinarily be sufficient to
+`go`/`optimize`, but the immutable v1 stop condition is explicit that a failed near-lossless
+quality lane overrides speed/fit benefits ("indicates a broken runtime rather than a quantization
+trade-off"). This decision uses only the locked v1 thresholds and this session's freshly measured
+metrics; no threshold was changed, and no distributed-implementation result (DGR-024's gRPC
+harness or any other distributed-lane evidence) was read or ingested to produce it.
+
+This reproduces DGR-001's original `stop` verdict on the same plan on the same real machine,
+confirming that verdict is stable over time and not an artifact of a single run.
+
+## Limitations
+
+- This is a **0.5B CPU baseline** (`Qwen/Qwen2.5-0.5B-Instruct`), the same generic model DGR-001
+  and DGR-019's `locked_elsewhere` reference use — not DeepSeek V4 Flash. DGR-019's evidence
+  already recorded that a DeepSeek V4 Flash `controlled-safetensors`/`whole-model-gguf` baseline is
+  not yet pinned; that is separate future work (see DGR-019's `v4-flash-distributed.reference_
+  baseline` note), not something this story's acceptance criteria ask it to create — it asks only
+  to run the exact already-locked lanes, which are this DGR-001 plan.
+  - The `whole-model-gguf` quality-lane exact-match divergence (0.33 vs 0.90 required) reproduces
+  identically and remains unexplained; this story does not diagnose it further beyond confirming
+  it reproduces (DGR-001's `quality-parity-diagnosis.md` documents the CPU-vs-ROCm split already
+  known).
+- Absolute timings are single-developer-machine measurements with ordinary run-to-run variance;
+  the locked ratios/ratios-vs-threshold crossings are the durable evidence, not the raw absolute
+  tok/s figures.
+- No new GPU (ROCm) diagnostic was re-run in this session — DGR-001's existing GPU diagnostic is
+  cited as prior evidence only; it uses a distinct signed `run_configured_gpu_diagnostic/v1`
+  producer that the v1 evaluator does not accept, so it cannot itself change the `stop` verdict
+  above.
+
+## Files changed
+
+- `.scratch/distributed-gguf-runtime/evidence/DGR-020/benchmark-config.json` (new) — byte-identical
+  copy of DGR-001's locked plan.
+- `.scratch/distributed-gguf-runtime/evidence/DGR-020/performance-contract.json` (new) —
+  byte-identical copy of DGR-001's immutable v1 thresholds.
+- `.scratch/distributed-gguf-runtime/evidence/DGR-020/results.json` / `results.txt` (new) — raw
+  signed real evidence from this session's fresh run.
+- `.scratch/distributed-gguf-runtime/evidence/DGR-020/baseline.json` / `contract-evaluation.json`
+  (new) — distilled baseline and fail-closed v1 verdict for this session's run.
+- `.scratch/distributed-gguf-runtime/evidence/DGR-020/README.md` (new, this file).
+- `.scratch/distributed-gguf-runtime/prd.json` — restored the dropped top-level
+  `sourceOfTruth`/`qualityGates`/`metadataSchema`/`milestones`/`supersededStories` objects (see
+  above); marked `DGR-020.passes = true` with `completionNotes`.
+- `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md` —
+  regenerated via `python scripts/ralph_prd_schema.py render` to reflect `passes: true`.
+
+No source or test files under `packages/` or `tests/` were changed by this story.
+
+## Commands and results
+
+```bash
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+```
+```text
+OK: 55 stories validated.
+```
+
+```bash
+.venv-rocm/bin/python -m pytest -q tests/test_recipe_benchmark.py tests/test_dgr_performance_contract.py tests/test_ralph_prd_schema.py
+```
+```text
+164 passed in 0.69s
+```
+
+```bash
+.venv-rocm/bin/python -m compileall -q packages tests
+```
+Exit code 0, no output (all files compile).
+
+```bash
+git diff --check
+```
+Exit code 0 (no whitespace errors).
+
+## Dependency handoff
+
+DGR-054 (enforce the alpha gate) may cite this evidence when it fills in
+`alpha.useful_speed.human_approval` — this is fresh, independently-collected, signed real-hardware
+evidence that the `controlled-safetensors`/`whole-model-gguf` v1 contract still holds `stop` on the
+current machine, immediately before any distributed-lane result exists, but it is a 0.5B CPU
+baseline, not the DeepSeek V4 Flash target; DGR-044 must still pin the V4 Flash reference baseline
+separately before DGR-054/DGR-070 can judge `dense-distributed-gguf`/`v4-flash-distributed` against
+it. No threshold in either `meshnet_node.performance_contract` or `meshnet_node.dgr_performance`
+was changed by this story.
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/baseline.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/baseline.json
@@ -0,0 +1,169 @@
+{
+  "artifact_sha256": {
+    "llama-cpp-near-lossless-quality": "e842fdc35d7f00fda95a54e1b51731ba1d196aea45065cc9f46925fdc1d6f862",
+    "llama-cpp-quantized-performance-fit": "a88e3f570e2efeaf06b50df9859db2c70d8646aa3a2c94a14e14d5797a2921a5",
+    "transformers-safetensors-reference": "e596e9d6205fdc9177569cccd7f8b471b058f66e3630c8e4326d5aad52bd18b6"
+  },
+  "backend_detail": {
+    "llama-cpp-near-lossless-quality": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64; binary sha256 fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd; threads 16; parallel slots 4; ctx/slot 512; gpu layers 0",
+    "llama-cpp-quantized-performance-fit": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64; binary sha256 fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd; threads 16; parallel slots 4; ctx/slot 512; gpu layers 0",
+    "transformers-safetensors-reference": "torch 2.10.0+rocm7.13.0a20260513; dtype bfloat16; device cpu; intra-op threads 16"
+  },
+  "evidence_class": "local-real",
+  "host": {
+    "accelerator_name": "Radeon 8060S Graphics",
+    "accelerator_runtime": "7.13.26183",
+    "benchmark_lane": "cpu-controlled-baseline",
+    "converter_sha256": "c819f18fb22927b49fabc3b35d1c9e21ee638b3817eccd1bd4efbcc7116eeb4d",
+    "cpu_count": 32,
+    "cuda_available": true,
+    "hostname": "fedora",
+    "llama_cpp_commit": "e920c523e3b8a0163fe498af5bf90df35ff51d25",
+    "llama_cpp_version": "9991",
+    "llama_server_identities": {
+      "/run/media/popov/d/DEV/llamacpp/llama.cpp/build/bin/llama-server": {
+        "sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+        "version": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64"
+      }
+    },
+    "llama_server_sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+    "platform": "Linux-7.0.14-101.fc43.x86_64-x86_64-with-glibc2.42",
+    "python": "3.12.13",
+    "quantizer_sha256": "bd0cc8c7be6d48aad4755b31062e0e59a887cbadd43dbb8771853d5858bb198f",
+    "torch_version": "2.10.0+rocm7.13.0a20260513",
+    "transformers_version": "5.13.0"
+  },
+  "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+  "model_revision": "7ae557604adf67be50417f59c2c2f167def9a775",
+  "plan_sha256": "efe24690a9a7164bac6ab3fd0a6b22f078fc08aaefcfb96210ddf154e6050570",
+  "provenance": {
+    "completed_at": "2026-07-22T05:52:30.445799Z",
+    "config_sha256": "00b2cce3e2f281bdf92fc5304ba5cac915a178ffccd3b9a25995ce39c00b90d3",
+    "producer": "meshnet_node.recipe_drivers.run_configured_benchmark/v1",
+    "run_id": "59b12968-c5d0-4391-90f4-0cd2aff77b21",
+    "schema_version": 1,
+    "signature": "aExtG1Y0fWFaqlKEtUOOpXZrganVAxbLvpov2WVgm19eNJ50VheeI7CuRhlWx4SJX9OFto2WuLaVPhjwSA88Cw==",
+    "signature_algorithm": "ed25519",
+    "signer_public_key_sha256": "8baca8742d9b3ed0c3fc54929c23f75ec8c1c739900aaf5334780d598ffa84de",
+    "started_at": "2026-07-22T05:51:36.511891Z"
+  },
+  "recipe_runtime": {
+    "llama-cpp-near-lossless-quality": {
+      "device": "cpu",
+      "runtime": "llama.cpp-9991-e920c523",
+      "weight_format": "gguf",
+      "weight_quantization": "bfloat16"
+    },
+    "llama-cpp-quantized-performance-fit": {
+      "device": "cpu",
+      "runtime": "llama.cpp-9991-e920c523",
+      "weight_format": "gguf",
+      "weight_quantization": "Q4_K_M"
+    },
+    "transformers-safetensors-reference": {
+      "device": "cpu",
+      "runtime": "transformers-5.13.0",
+      "weight_format": "safetensors",
+      "weight_quantization": "bfloat16"
+    }
+  },
+  "recipes": {
+    "llama-cpp-near-lossless-quality": {
+      "artifact_bytes": 994156448,
+      "available": true,
+      "concurrency": {
+        "1": {
+          "aggregate_decode_tokens_per_sec": 89.2873,
+          "decode_tokens_per_sec": 102.5344,
+          "failures": 0,
+          "latency_p50_ms": 316.647,
+          "latency_p95_ms": 374.8515,
+          "peak_rss_bytes": 1110106112,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 1740.0213,
+          "ttft_p50_ms": 15.067,
+          "ttft_p95_ms": 65.191
+        },
+        "4": {
+          "aggregate_decode_tokens_per_sec": 218.1128,
+          "decode_tokens_per_sec": 80.0623,
+          "failures": 0,
+          "latency_p50_ms": 403.9781,
+          "latency_p95_ms": 767.6557,
+          "peak_rss_bytes": 1139265536,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 1064.6179,
+          "ttft_p50_ms": 36.611,
+          "ttft_p95_ms": 178.801
+        }
+      },
+      "device": "cpu",
+      "lane": "quality"
+    },
+    "llama-cpp-quantized-performance-fit": {
+      "artifact_bytes": 397807520,
+      "available": true,
+      "concurrency": {
+        "1": {
+          "aggregate_decode_tokens_per_sec": 149.8675,
+          "decode_tokens_per_sec": 213.1452,
+          "failures": 0,
+          "latency_p50_ms": 161.7164,
+          "latency_p95_ms": 282.5491,
+          "peak_rss_bytes": 541663232,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 1181.0842,
+          "ttft_p50_ms": 17.252,
+          "ttft_p95_ms": 130.529
+        },
+        "4": {
+          "aggregate_decode_tokens_per_sec": 235.6963,
+          "decode_tokens_per_sec": 94.7604,
+          "failures": 0,
+          "latency_p50_ms": 373.7211,
+          "latency_p95_ms": 759.3151,
+          "peak_rss_bytes": 571027456,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 567.7335,
+          "ttft_p50_ms": 42.086,
+          "ttft_p95_ms": 312.645
+        }
+      },
+      "device": "cpu",
+      "lane": "performance-fit"
+    },
+    "transformers-safetensors-reference": {
+      "artifact_bytes": 999586347,
+      "available": true,
+      "concurrency": {
+        "1": {
+          "aggregate_decode_tokens_per_sec": 44.4625,
+          "decode_tokens_per_sec": 50.8327,
+          "failures": 0,
+          "latency_p50_ms": 701.9146,
+          "latency_p95_ms": 776.2706,
+          "peak_rss_bytes": 1933221888,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 699.7553,
+          "ttft_p50_ms": 32.8569,
+          "ttft_p95_ms": 173.7161
+        },
+        "4": {
+          "aggregate_decode_tokens_per_sec": 48.849,
+          "decode_tokens_per_sec": 13.4779,
+          "failures": 0,
+          "latency_p50_ms": 2503.1601,
+          "latency_p95_ms": 2600.6307,
+          "peak_rss_bytes": 2170908672,
+          "peak_vram_bytes": 0,
+          "prefill_tokens_per_sec": 264.5822,
+          "ttft_p50_ms": 95.7502,
+          "ttft_p95_ms": 425.4973
+        }
+      },
+      "device": "cpu",
+      "lane": "quality"
+    }
+  },
+  "reference_recipe_id": "transformers-safetensors-reference"
+}
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/benchmark-config.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/benchmark-config.json
@@ -0,0 +1,118 @@
+{
+  "artifact_storage_root": "/run/media/popov/DATA/llm",
+  "evidence_class": "local-real",
+  "host": {
+    "benchmark_lane": "cpu-controlled-baseline",
+    "llama_cpp_commit": "e920c523e3b8a0163fe498af5bf90df35ff51d25",
+    "llama_cpp_version": "9991",
+    "llama_server_sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+    "converter_sha256": "c819f18fb22927b49fabc3b35d1c9e21ee638b3817eccd1bd4efbcc7116eeb4d",
+    "quantizer_sha256": "bd0cc8c7be6d48aad4755b31062e0e59a887cbadd43dbb8771853d5858bb198f",
+    "transformers_version": "5.13.0"
+  },
+  "plan": {
+    "plan_id": "dgr-001-controlled-whole-model-baseline-v1",
+    "model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+    "model_revision": "7ae557604adf67be50417f59c2c2f167def9a775",
+    "prompts": [
+      {
+        "id": "short-fact",
+        "text": "The capital of France is",
+        "context_class": "short"
+      },
+      {
+        "id": "medium-code",
+        "text": "Complete this Python function without commentary:\n\ndef fibonacci(n):\n    \"\"\"Return the nth Fibonacci number for n >= 0.\"\"\"\n",
+        "context_class": "medium"
+      },
+      {
+        "id": "long-summary",
+        "text": "A distributed inference service divides a transformer across consumer machines. The tracker owns admission, routing, cancellation, accounting, and telemetry, while workers own only model execution. Every request carries an immutable model identity and revision. Workers must reject incompatible protocol versions and resource demands before allocating large buffers. Activation tensors are chunked, checksummed, bounded by negotiated limits, and propagated with explicit flow-control credits. A caller may disconnect at any time, so cancellation must release queued work, in-flight transfers, and cache reservations without double billing. Retries can occur after network failures, requiring idempotent request identifiers and deterministic completion accounting. The system keeps the existing safetensors path as a correctness reference while a native GGUF path is measured. Benchmarks compare the same prompts, output lengths, sampling policy, device, and concurrency, and they separate near-lossless quality checks from quantized speed and fit claims. Summarize the design priorities in three concise bullet points.",
+        "context_class": "long"
+      }
+    ],
+    "sampling": {
+      "temperature": 0.0,
+      "top_p": 1.0,
+      "top_k": 1,
+      "seed": 1234,
+      "max_output_tokens": 32
+    },
+    "concurrency_levels": [1, 4],
+    "repeats": 3,
+    "warmup_requests": 2
+  },
+  "recipes": [
+    {
+      "id": "transformers-safetensors-reference",
+      "runtime": "transformers-5.13.0",
+      "weight_format": "safetensors",
+      "weight_quantization": "bfloat16",
+      "lane": "quality",
+      "device": "cpu",
+      "artifact_path": "/run/media/popov/DATA/llm/safetensor/models/models--Qwen--Qwen2.5-0.5B-Instruct/snapshots/7ae557604adf67be50417f59c2c2f167def9a775",
+      "artifact_sha256": "e596e9d6205fdc9177569cccd7f8b471b058f66e3630c8e4326d5aad52bd18b6",
+      "source_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+      "source_model_revision": "7ae557604adf67be50417f59c2c2f167def9a775",
+      "is_reference": true,
+      "notes": "artifact_sha256 is the deterministic digest of every snapshot path and file byte",
+      "driver": {
+        "type": "transformers",
+        "model_path": "/run/media/popov/DATA/llm/safetensor/models/models--Qwen--Qwen2.5-0.5B-Instruct/snapshots/7ae557604adf67be50417f59c2c2f167def9a775",
+        "device": "cpu",
+        "dtype": "bfloat16",
+        "threads": 16
+      }
+    },
+    {
+      "id": "llama-cpp-near-lossless-quality",
+      "runtime": "llama.cpp-9991-e920c523",
+      "weight_format": "gguf",
+      "weight_quantization": "bfloat16",
+      "lane": "quality",
+      "device": "cpu",
+      "artifact_path": "/run/media/popov/DATA/llm/dgr-001/Qwen2.5-0.5B-Instruct-7ae5576-BF16.gguf",
+      "artifact_sha256": "e842fdc35d7f00fda95a54e1b51731ba1d196aea45065cc9f46925fdc1d6f862",
+      "source_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+      "source_model_revision": "7ae557604adf67be50417f59c2c2f167def9a775",
+      "is_reference": false,
+      "notes": "Converted directly from the exact mounted safetensors revision while preserving BF16 weights with pinned llama.cpp",
+      "driver": {
+        "type": "llama-cpp-server",
+        "binary": "/run/media/popov/d/DEV/llamacpp/llama.cpp/build/bin/llama-server",
+        "binary_sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+        "gguf_path": "/run/media/popov/DATA/llm/dgr-001/Qwen2.5-0.5B-Instruct-7ae5576-BF16.gguf",
+        "device": "cpu",
+        "threads": 16,
+        "n_parallel": 4,
+        "context_per_slot": 512,
+        "n_gpu_layers": 0
+      }
+    },
+    {
+      "id": "llama-cpp-quantized-performance-fit",
+      "runtime": "llama.cpp-9991-e920c523",
+      "weight_format": "gguf",
+      "weight_quantization": "Q4_K_M",
+      "lane": "performance-fit",
+      "device": "cpu",
+      "artifact_path": "/run/media/popov/DATA/llm/dgr-001/Qwen2.5-0.5B-Instruct-7ae5576-Q4_K_M.gguf",
+      "artifact_sha256": "a88e3f570e2efeaf06b50df9859db2c70d8646aa3a2c94a14e14d5797a2921a5",
+      "source_model_id": "Qwen/Qwen2.5-0.5B-Instruct",
+      "source_model_revision": "7ae557604adf67be50417f59c2c2f167def9a775",
+      "is_reference": false,
+      "notes": "Quantized from the exact-revision F16 GGUF with pinned llama-quantize",
+      "driver": {
+        "type": "llama-cpp-server",
+        "binary": "/run/media/popov/d/DEV/llamacpp/llama.cpp/build/bin/llama-server",
+        "binary_sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+        "gguf_path": "/run/media/popov/DATA/llm/dgr-001/Qwen2.5-0.5B-Instruct-7ae5576-Q4_K_M.gguf",
+        "device": "cpu",
+        "threads": 16,
+        "n_parallel": 4,
+        "context_per_slot": 512,
+        "n_gpu_layers": 0
+      }
+    }
+  ]
+}
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/contract-evaluation.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/contract-evaluation.json
@@ -0,0 +1,71 @@
+{
+  "contract_version": 1,
+  "fit_benefit": true,
+  "plan_id": "dgr-001-controlled-whole-model-baseline-v1",
+  "quality_lane_pass": false,
+  "rationale": [
+    "the near-lossless quality lane failed: the GGUF runtime disagrees with the safetensors reference beyond what near-lossless weights can explain",
+    "a meaningful speed benefit was measured",
+    "a meaningful fit benefit was measured"
+  ],
+  "recipes": [
+    {
+      "comparable": true,
+      "failures": 0,
+      "fit_benefit": false,
+      "incomparable_reason": "",
+      "lane": "quality",
+      "measurements": {
+        "aggregate_concurrency": 4,
+        "aggregate_throughput_speedup": 4.465,
+        "artifact_size_ratio": 0.9946,
+        "artifact_size_win": false,
+        "compared_prompts": 3,
+        "decode_speedup": 2.0171,
+        "exact_match_rate": 0.3333,
+        "expected_prompts": 3,
+        "failure_rate": 0.0,
+        "mean_similarity": 0.9471,
+        "resident_memory_ratio": 0.5742,
+        "ttft_ratio": 0.4586
+      },
+      "quality_pass": false,
+      "reasons": [
+        "single-request decode 2.02x reference (>= 1.25x) at TTFT ratio 0.46",
+        "aggregate throughput at concurrency 4 is 4.46x reference (>= 1.25x)",
+        "peak resident memory is 0.57x reference (<= 0.75x)",
+        "quality lane exact-match 0.33 / similarity 0.947 versus the reference (fail)"
+      ],
+      "recipe_id": "llama-cpp-near-lossless-quality",
+      "speed_benefit": false
+    },
+    {
+      "comparable": true,
+      "failures": 0,
+      "fit_benefit": true,
+      "incomparable_reason": "",
+      "lane": "performance-fit",
+      "measurements": {
+        "aggregate_concurrency": 4,
+        "aggregate_throughput_speedup": 4.825,
+        "artifact_size_ratio": 0.398,
+        "artifact_size_win": true,
+        "decode_speedup": 4.1931,
+        "failure_rate": 0.0,
+        "resident_memory_ratio": 0.2802,
+        "ttft_ratio": 0.5251
+      },
+      "quality_pass": null,
+      "reasons": [
+        "single-request decode 4.19x reference (>= 1.25x) at TTFT ratio 0.53",
+        "aggregate throughput at concurrency 4 is 4.83x reference (>= 1.25x)",
+        "peak resident memory is 0.28x reference (<= 0.75x)"
+      ],
+      "recipe_id": "llama-cpp-quantized-performance-fit",
+      "speed_benefit": true
+    }
+  ],
+  "speed_benefit": true,
+  "stop_condition_met": true,
+  "verdict": "stop"
+}
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/performance-contract.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/performance-contract.json
@@ -0,0 +1,87 @@
+{
+  "schema_version": 1,
+  "contract_version": 1,
+  "locked_at": "2026-07-13T00:00:00Z",
+  "locked_by": "DGR-001",
+  "plan_id": "dgr-001-controlled-whole-model-baseline-v1",
+  "thresholds": {
+    "min_decode_speedup": 1.25,
+    "max_ttft_ratio": 1.25,
+    "min_aggregate_throughput_speedup": 1.25,
+    "max_resident_memory_ratio": 0.75,
+    "max_artifact_size_ratio": 0.6,
+    "min_quality_exact_match_rate": 0.9,
+    "min_quality_mean_similarity": 0.97,
+    "max_failure_rate": 0.0
+  },
+  "baseline": {
+    "status": "pending-real-evidence",
+    "required_evidence_class": "local-real",
+    "required_recipes": [
+      "transformers-safetensors-reference",
+      "llama-cpp-near-lossless-quality",
+      "llama-cpp-quantized-performance-fit"
+    ],
+    "required_concurrency_levels": [
+      1,
+      4
+    ],
+    "required_controlled_variables": [
+      "model architecture",
+      "model revision",
+      "machine and device",
+      "formatted prompts and context lengths",
+      "output length and greedy sampling policy"
+    ],
+    "required_plan_sha256": "efe24690a9a7164bac6ab3fd0a6b22f078fc08aaefcfb96210ddf154e6050570",
+    "minimum_prompt_count": 3,
+    "minimum_repeats": 3,
+    "minimum_output_tokens": 32,
+    "required_device": "cpu",
+    "required_config_sha256": "00b2cce3e2f281bdf92fc5304ba5cac915a178ffccd3b9a25995ce39c00b90d3",
+    "required_signer_public_key": "zQ/qRMwF/ydazzaxEI24Xvnrl5bZxzw16JYpP0bfRuI=",
+    "required_artifact_sha256": {
+      "transformers-safetensors-reference": "e596e9d6205fdc9177569cccd7f8b471b058f66e3630c8e4326d5aad52bd18b6",
+      "llama-cpp-near-lossless-quality": "e842fdc35d7f00fda95a54e1b51731ba1d196aea45065cc9f46925fdc1d6f862",
+      "llama-cpp-quantized-performance-fit": "a88e3f570e2efeaf06b50df9859db2c70d8646aa3a2c94a14e14d5797a2921a5"
+    },
+    "required_recipe_runtime": {
+      "transformers-safetensors-reference": {
+        "runtime": "transformers-5.13.0",
+        "weight_format": "safetensors",
+        "weight_quantization": "bfloat16",
+        "device": "cpu"
+      },
+      "llama-cpp-near-lossless-quality": {
+        "runtime": "llama.cpp-9991-e920c523",
+        "weight_format": "gguf",
+        "weight_quantization": "bfloat16",
+        "device": "cpu"
+      },
+      "llama-cpp-quantized-performance-fit": {
+        "runtime": "llama.cpp-9991-e920c523",
+        "weight_format": "gguf",
+        "weight_quantization": "Q4_K_M",
+        "device": "cpu"
+      }
+    },
+    "required_backend_detail": {
+      "transformers-safetensors-reference": "torch 2.10.0+rocm7.13.0a20260513; dtype bfloat16; device cpu; intra-op threads 16",
+      "llama-cpp-near-lossless-quality": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64; binary sha256 fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd; threads 16; parallel slots 4; ctx/slot 512; gpu layers 0",
+      "llama-cpp-quantized-performance-fit": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64; binary sha256 fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd; threads 16; parallel slots 4; ctx/slot 512; gpu layers 0"
+    },
+    "required_host_identity": {
+      "python": "3.12.13",
+      "torch_version": "2.10.0+rocm7.13.0a20260513",
+      "transformers_version": "5.13.0",
+      "llama_server_identities": {
+        "/run/media/popov/d/DEV/llamacpp/llama.cpp/build/bin/llama-server": {
+          "sha256": "fd8fe612970f23e447f2e717cfa51665be06b8d7315ba60556e010f6bca510dd",
+          "version": "version: 9991 (e920c523) | built with GNU 15.2.1 for Linux x86_64"
+        }
+      }
+    }
+  },
+  "stop_condition": "Stop the native llama.cpp/GGUF track when, on the same machine and device as the Transformers/safetensors reference and under this plan, no performance-fit GGUF recipe delivers either a meaningful speed benefit (>=25% higher single-request decode tokens/sec without a >25% worse TTFT, or >=25% higher aggregate throughput under concurrency) or a meaningful fit benefit (>=25% lower peak resident memory), or when the near-lossless quality lane fails, which indicates a broken runtime rather than a quantization trade-off.",
+  "notes": "Quantized performance-fit output drift is reported as advisory only. It is not numerical-equivalence evidence. DGR-014 consumes this immutable v1 contract. Non-synthetic evidence must be Ed25519-signed by the pinned key and match the exact locked config, artifacts, runtimes, backends, and host runtime identity."
+}
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/results.json
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/results.json
--- a/.scratch/distributed-gguf-runtime/evidence/DGR-020/results.txt
+++ b/.scratch/distributed-gguf-runtime/evidence/DGR-020/results.txt
@@ -0,0 +1,10 @@
+Recipe benchmark dgr-001-controlled-whole-model-baseline-v1 (local-real)
+model Qwen/Qwen2.5-0.5B-Instruct@7ae557604adf67be50417f59c2c2f167def9a775
+transformers-safetensors-reference     [quality         ] c= 1 ttft p50/p95     32.9/   173.7 ms; prefill   699.8 tok/s; decode   50.8 tok/s; aggregate    44.5 tok/s; rss  1.93 GB; vram  0.00 GB; artifact  1.00 GB; failures 0
+transformers-safetensors-reference     [quality         ] c= 4 ttft p50/p95     95.8/   425.5 ms; prefill   264.6 tok/s; decode   13.5 tok/s; aggregate    48.8 tok/s; rss  2.17 GB; vram  0.00 GB; artifact  1.00 GB; failures 0
+llama-cpp-near-lossless-quality        [quality         ] c= 1 ttft p50/p95     15.1/    65.2 ms; prefill  1740.0 tok/s; decode  102.5 tok/s; aggregate    89.3 tok/s; rss  1.11 GB; vram  0.00 GB; artifact  0.99 GB; failures 0
+llama-cpp-near-lossless-quality        [quality         ] c= 4 ttft p50/p95     36.6/   178.8 ms; prefill  1064.6 tok/s; decode   80.1 tok/s; aggregate   218.1 tok/s; rss  1.14 GB; vram  0.00 GB; artifact  0.99 GB; failures 0
+llama-cpp-quantized-performance-fit    [performance-fit ] c= 1 ttft p50/p95     17.3/   130.5 ms; prefill  1181.1 tok/s; decode  213.1 tok/s; aggregate   149.9 tok/s; rss  0.54 GB; vram  0.00 GB; artifact  0.40 GB; failures 0
+llama-cpp-quantized-performance-fit    [performance-fit ] c= 4 ttft p50/p95     42.1/   312.6 ms; prefill   567.7 tok/s; decode   94.8 tok/s; aggregate   235.7 tok/s; rss  0.57 GB; vram  0.00 GB; artifact  0.40 GB; failures 0
+drift llama-cpp-near-lossless-quality  vs transformers-safetensors-reference exact 0.33; similarity 0.947 (gated)
+drift llama-cpp-quantized-performance-fit vs transformers-safetensors-reference exact 0.00; similarity 0.456 (advisory)