feat: checkpoint distributed gguf runtime stories

.scratch/distributed-gguf-runtime/evidence/DGR-009/README.md

@@ -0,0 +1,83 @@
+# DGR-009 — Integrate the native worker with Meshnet: evidence
+
+Status: done
+Date: 2026-07-15
+Evidence kind: **python-unit + repo-hygiene**. No model download, no GPU, no API
+credit.
+
+## Summary
+
+Implemented the Meshnet-facing GGUF backend seam and recipe gating needed for
+the native worker path:
+
+- Added `GgufNodeBackend`, a backend-shaped adapter that lets the existing node
+  HTTP/control-plane code serve GGUF-backed shards without changing the
+  Transformers/Torch path for the default recipes.
+- Added `llama-cpp-native` to the recipe manifest and gated startup so only
+  recipes with `backend_id == "llama.cpp"` build the GGUF backend.
+- Preserved the existing registration/admission flow by carrying the validated
+  capability report and proof shard through registration.
+- Added unit coverage for the GGUF backend seam and for recipe-gated startup.
+- Fixed the explicit-shard startup path so the legacy Torch tests that use an
+  opaque stub model still pass without requiring HuggingFace config discovery.
+
+## Files changed
+
+- `packages/node/meshnet_node/gguf_backend.py` - new GGUF backend adapter and
+  worker-transport boundary.
+- `packages/node/meshnet_node/startup.py` - recipe-gated GGUF backend injection
+  and explicit-shard startup fix.
+- `packages/node/meshnet_node/recipes.json` - added `llama-cpp-native`.
+- `tests/test_gguf_backend.py` - backend delegation and recipe-selection tests.
+- `.ralph-tui/progress.md` - appended DGR-009 progress note.
+- `.scratch/distributed-gguf-runtime/issues/09-integrate-the-native-worker-with-meshnet.md`
+  - marked `Status: done`.
+
+## Commands and real results
+
+```bash
+python -m pytest -q tests/test_gguf_backend.py
+# -> 2 passed in 0.05s
+
+python -m pytest -q tests/test_node_admission.py::test_the_served_backend_is_loaded_with_the_recipe_that_was_validated tests/test_node_admission.py::test_backend_validation_failure_registers_nothing
+# -> 2 passed in 0.07s
+
+python -m compileall -q packages tests
+# -> exit 0
+
+git diff --check
+# -> exit 0
+
+python -m pytest -q
+# -> 222 failed, 463 passed, 13 skipped, 86 errors in 135.65s
+```
+
+## Limitations
+
+- `python -m pytest -q` is still not clean in this sandbox. The dominant
+  failures are tracker/control-plane socket `PermissionError: [Errno 1]
+  Operation not permitted` and a native protocol import failure caused by a
+  protobuf runtime mismatch (`gencode 7.35.0` vs runtime `6.33.6`).
+- `tests/test_native_shard_protocol.py` currently fails for the same protobuf
+  runtime mismatch in this environment.
+- `DGR-008` evidence was not present in the tree, so the dependency behavior was
+  verified by reading the live code and exercising the Python seam instead of
+  relying on a missing README.
+
+## Compatibility notes
+
+- The default Torch path remains intact; GGUF backend selection is explicit and
+  recipe-gated.
+- `TorchNodeServer` already accepts an injected backend object, so the control
+  plane stays Meshnet-owned.
+- The GGUF adapter currently establishes the seam for the native worker
+  transport; the compiled worker remains the owner of the gRPC protocol details.
+
+## Dependent-story handoff
+
+- DGR-008 should continue to own the native worker implementation and the
+  versioned gRPC frame handling behind `MESHNET_NATIVE_WORKER_URL`.
+- DGR-010 / DGR-012 can build on this seam without changing the control plane:
+  the recipe-gated backend and validated capability report are already carried
+  through startup.
+