102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# Native Shard protocol
|
|
|
|
`proto/shard_runtime.proto` is the semantic contract between a Meshnet node and
|
|
a Shard worker: Protocol Buffers over gRPC/HTTP2 (ADR-0020). It is the source of
|
|
truth. The Python and C++ types are generated from it; neither is the contract.
|
|
|
|
## What lives here
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `proto/shard_runtime.proto` | The schema: capability, health, session stream, release, cancel |
|
|
| `testdata/*.binpb` | Committed conformance vectors both languages assert against |
|
|
| `tests/test_shard_protocol_conformance.cpp` | C++ conformance test |
|
|
| `CMakeLists.txt` | C++ generation, build wiring, and `ctest` registration |
|
|
|
|
The Python stubs are generated into
|
|
`packages/node/meshnet_node/native_protocol/generated/` and are committed, so
|
|
installing a node needs no protoc. The C++ stubs are generated into the build
|
|
tree and are never committed — a C++ consumer already has a toolchain, and a
|
|
committed copy could only rot.
|
|
|
|
## Regenerating
|
|
|
|
```bash
|
|
pip install grpcio-tools==1.82.1 # bundles protoc; no system protoc needed
|
|
python scripts/generate_native_protocol.py # rewrite the Python stubs
|
|
python scripts/generate_native_protocol.py --check # fail if they drifted
|
|
python scripts/generate_protocol_goldens.py --check # fail if the vectors drifted
|
|
```
|
|
|
|
Both `--check` modes run in CI via `tests/test_native_shard_protocol.py`, so a
|
|
schema edit that is not accompanied by regenerated output fails the suite rather
|
|
than shipping stubs that disagree with the schema they claim to implement.
|
|
|
|
## DGR-006 decode and tail compatibility
|
|
|
|
`DecodeStep.bundle` is the versioned `TensorBundle` fast-path boundary. It is
|
|
authoritative whenever present and supports architecture sidebands. The original
|
|
`DecodeStep.tensor` remains readable as the compact one-tensor encoding for
|
|
certified boundaries that need only one tensor; new readers wrap it into a
|
|
one-member bundle. Tail completions use `TailResult`, which binds logits or a
|
|
sampled token to request/recipe identity and sampling/template/reasoning inputs.
|
|
|
|
## Building and running the C++ conformance test
|
|
|
|
If the machine has no protobuf C++ toolchain:
|
|
|
|
```bash
|
|
bash scripts/bootstrap_native_toolchain.sh build/native-toolchain
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
cmake -S packages/node/native -B build/native \
|
|
-DCMAKE_PREFIX_PATH="$PWD/build/native-toolchain"
|
|
cmake --build build/native -j
|
|
ctest --test-dir build/native --output-on-failure
|
|
```
|
|
|
|
The bootstrap pins and builds Protobuf `33.1`, gRPC C++ `1.82.1`, and the
|
|
matching `grpc_cpp_plugin` into one ignored prefix. CMake requires those exact
|
|
package versions and always generates both message and service stubs; it does
|
|
not fall back to an arbitrary system plugin.
|
|
|
|
## How the cross-language check actually proves something
|
|
|
|
Two codecs that each round-trip their own output prove only that each is
|
|
self-consistent. Instead:
|
|
|
|
1. Python builds the canonical message and commits its bytes to `testdata/`.
|
|
2. The C++ test parses *those* bytes, asserts every field, independently
|
|
recomputes the CRC32C from the polynomial, and re-serializes to
|
|
`cpp_roundtrip.binpb` in the build tree.
|
|
3. `test_cpp_and_python_agree_byte_for_byte` compares that file to the golden.
|
|
|
|
Byte equality across the two implementations is the claim; anything less is two
|
|
parallel test suites that can drift apart.
|
|
|
|
## DGR-037 standalone llama.cpp worker
|
|
|
|
`shard_worker` is no longer a model-free fixture. It refuses to start until it
|
|
can load one exact, range-attested GGUF identity through the pinned patched
|
|
llama.cpp library. Supply these environment variables from the node-owned
|
|
recipe/materialization layer (never from a stream request):
|
|
|
|
```bash
|
|
MESHNET_MODEL_ARTIFACT=/mounted/models/model.gguf \
|
|
MESHNET_MODEL_ARTIFACT_DIGEST=sha256:<artifact> \
|
|
MESHNET_RUNTIME_RECIPE_DIGEST=sha256:<recipe> \
|
|
MESHNET_RECIPE_ID=dense-llama MESHNET_RECIPE_VERSION=1 MESHNET_CATALOGUE_VERSION=1 \
|
|
MESHNET_SHARD_START_LAYER=0 MESHNET_SHARD_END_LAYER=32 \
|
|
build/native/shard_worker 127.0.0.1:50051
|
|
```
|
|
|
|
The worker publishes that loaded identity and llama.cpp-derived resident bytes
|
|
in capability/health responses, and only accepts the exact same range and
|
|
fingerprint at `SessionOpen`. `MESHNET_INJECT_PROCESS_DEATH_AFTER_EXECUTIONS=N`
|
|
is an opt-in test hook: after the Nth admitted execution the process exits 70,
|
|
which is intentionally observable by the future node supervisor; it is not a
|
|
recover-in-process mechanism.
|