feat: DGR-002 - Adopt the versioned gRPC Shard protocol

packages/node/native/README.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Building and running the C++ conformance test
+
+If the machine has no protobuf C++ toolchain:
+
+```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
+```
+
+gRPC C++ is optional: without it, CMake builds the message types only, which is
+all the conformance test needs. When gRPC C++ *is* found, the `ShardRuntime`
+service stubs are built too and exported as `shard_runtime_grpc` for the worker
+(DGR-008) to link.
+
+## 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.