# 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.