story: DGR-033 Build a standalone fake C++ gRPC Shard worker

packages/node/native/CMakeLists.txt

@@ -62,6 +62,21 @@ message(STATUS "Pinned gRPC ${gRPC_VERSION}: building ShardRuntime service stubs
 
 enable_testing()
 
+# The standalone fake Shard worker (DGR-033): a real gRPC server over the
+# ShardRuntime service, backed by the model-free FakeShardEngine. It links the
+# grpc service stubs only — no llama.cpp, no graph-execution entry point.
+add_executable(shard_worker
+  worker/shard_worker_main.cpp
+  worker/shard_service.cpp)
+target_include_directories(shard_worker PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/worker")
+target_link_libraries(shard_worker PRIVATE shard_runtime_grpc gRPC::grpc++)
+
+# Pure-C++ CTest: the worker binds an ephemeral port, self-drives the full
+# lifecycle (capability, health, fragmented prefill, decode, release) over a
+# real loopback gRPC channel, and exits non-zero on any mismatch. This proves
+# the worker serves the contract without needing a Python environment.
+add_test(NAME shard_worker_selftest COMMAND shard_worker --selftest)
+
 add_executable(shard_protocol_conformance tests/test_shard_protocol_conformance.cpp)
 target_link_libraries(shard_protocol_conformance PRIVATE shard_runtime_proto)
 

packages/node/native/worker/fake_engine.h

@@ -0,0 +1,164 @@
+// Deterministic, model-free fake ShardEngine for the native worker (DGR-033).
+//
+// This is the C++ analogue of `meshnet_node.fake_shard_engine.FakeShardEngine`
+// (DGR-032): a pure fixture that performs a *bounded real forward* over the
+// bytes it received off the socket and never links, loads, or dispatches to
+// llama.cpp. It exists to prove the standalone worker process, stream,
+// lifecycle, and supervision shape before any real engine is bound (DGR-037).
+//
+// The "forward" is deliberately transport-verifiable rather than semantic: it
+// reassembles a tensor's fragments, checks they tile exactly, and derives a
+// CRC32C over the uncompressed bytes — the same rule the schema's `Checksum`
+// declares and the same bounded forward the DGR-024 Python surface performs.
+// Feeding the same bytes back (echo) lets a client prove the payload truly
+// traversed the wire and returned unmodified; a direct hop and an opaque relay
+// of the identical frames therefore yield byte-identical responses.
+//
+// There is no arbitrary-graph entry point here and no llama.cpp RPC: the engine
+// only knows how to reassemble/checksum a bundle. That is the whole point of a
+// fixture worker (acceptance criterion 4).
+
+#ifndef MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_
+#define MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_
+
+#include <algorithm>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "shard_runtime.pb.h"
+
+namespace meshnet::worker {
+
+namespace sp = ::meshnet::shard::v1;
+
+// Standard CRC-32 (ISO-HDLC / zlib polynomial 0xEDB88320, reflected).
+//
+// The schema's `Checksum` field is labelled CRC32C, but the DGR-024 Python
+// runtime surface (`shard_runtime_server.py`) computes it with `zlib.crc32`
+// (standard CRC-32, not the Castagnoli CRC32C). This worker deliberately mirrors
+// that exact computation so its checksum acceptance is byte-for-byte identical
+// to the existing Python gRPC surface and to a relayed frame's expectations.
+inline uint32_t Crc32(const std::string& data, uint32_t seed = 0) {
+  static uint32_t table[256];
+  static bool built = false;
+  if (!built) {
+    for (uint32_t i = 0; i < 256; ++i) {
+      uint32_t c = i;
+      for (int k = 0; k < 8; ++k) {
+        c = (c & 1) ? (c >> 1) ^ 0xEDB88320u : (c >> 1);
+      }
+      table[i] = c;
+    }
+    built = true;
+  }
+  uint32_t crc = seed ^ 0xFFFFFFFFu;
+  for (unsigned char byte : data) {
+    crc = (crc >> 8) ^ table[(crc ^ byte) & 0xFF];
+  }
+  return crc ^ 0xFFFFFFFFu;
+}
+
+// Outcome of validating one bundle before the bounded forward runs.
+struct BundleCheck {
+  // Set when the bundle is malformed/corrupt (maps to PAYLOAD_CORRUPT).
+  std::optional<std::string> corrupt_detail;
+  // Set when the declared payload exceeds the negotiated per-chunk ceiling
+  // (maps to RESOURCE_EXHAUSTED) — the worker refuses unbounded messages.
+  std::optional<std::string> oversize_detail;
+};
+
+// The fake engine's only capability: verify a bundle tiles and checksums, and
+// that it stays within the negotiated byte ceiling. Mirrors `_validate_bundle`
+// in `shard_runtime_server.py` plus the bounded-message rule DGR-033 adds.
+class FakeShardEngine {
+ public:
+  // Marker mirroring `FakeShardEngine.EVIDENCE_CLASS` so a future parity check
+  // (DGR-036) can assert this is a fixture, not a real engine.
+  static constexpr const char* kEvidenceClass = "fixture";
+
+  explicit FakeShardEngine(uint64_t max_chunk_bytes) : max_chunk_bytes_(max_chunk_bytes) {}
+
+  BundleCheck Validate(const sp::TensorBundle& bundle) const {
+    BundleCheck result;
+    for (const auto& tensor : bundle.tensors()) {
+      // Bounded message: a declared payload larger than the ceiling is refused
+      // before any reassembly work is done.
+      if (max_chunk_bytes_ != 0 && tensor.total_bytes() > max_chunk_bytes_) {
+        result.oversize_detail =
+            "tensor '" + tensor.name() + "': declared total_bytes " +
+            std::to_string(tensor.total_bytes()) + " exceeds max_chunk_bytes " +
+            std::to_string(max_chunk_bytes_);
+        return result;
+      }
+
+      // Fragments must tile the wire body exactly: no hole, no overlap.
+      std::vector<const sp::TensorFragment*> ordered;
+      ordered.reserve(tensor.fragments_size());
+      for (const auto& fragment : tensor.fragments()) {
+        ordered.push_back(&fragment);
+      }
+      std::sort(ordered.begin(), ordered.end(),
+                [](const sp::TensorFragment* a, const sp::TensorFragment* b) {
+                  return a->byte_offset() < b->byte_offset();
+                });
+      uint64_t expected_offset = 0;
+      std::string payload;
+      for (const auto* fragment : ordered) {
+        if (fragment->byte_offset() != expected_offset) {
+          result.corrupt_detail =
+              "tensor '" + tensor.name() + "': fragment at offset " +
+              std::to_string(fragment->byte_offset()) +
+              " does not tile the preceding " + std::to_string(expected_offset) +
+              " bytes (gap or overlap)";
+          return result;
+        }
+        payload.append(fragment->payload());
+        expected_offset += fragment->payload().size();
+      }
+      if (tensor.compression() == sp::COMPRESSION_NONE &&
+          expected_offset != tensor.total_bytes()) {
+        result.corrupt_detail =
+            "tensor '" + tensor.name() + "': fragments cover " +
+            std::to_string(expected_offset) + " bytes, declared total_bytes is " +
+            std::to_string(tensor.total_bytes());
+        return result;
+      }
+      if (tensor.compression() == sp::COMPRESSION_NONE &&
+          tensor.checksum().algorithm() == sp::CHECKSUM_ALGORITHM_CRC32C) {
+        const uint32_t actual = Crc32(payload);
+        const std::string& declared = tensor.checksum().value();
+        std::string actual_be(4, '\0');
+        actual_be[0] = static_cast<char>((actual >> 24) & 0xFF);
+        actual_be[1] = static_cast<char>((actual >> 16) & 0xFF);
+        actual_be[2] = static_cast<char>((actual >> 8) & 0xFF);
+        actual_be[3] = static_cast<char>(actual & 0xFF);
+        if (declared != actual_be) {
+          result.corrupt_detail = "tensor '" + tensor.name() + "': checksum mismatch";
+          return result;
+        }
+      }
+    }
+    return result;
+  }
+
+  // Bounded real forward: fold every fragment's payload through CRC32C so the
+  // digest is only reproducible if the payload really traversed the wire.
+  uint32_t BoundedForward(const sp::TensorBundle& bundle) const {
+    uint32_t digest = 0;
+    for (const auto& tensor : bundle.tensors()) {
+      for (const auto& fragment : tensor.fragments()) {
+        digest = Crc32(fragment.payload(), digest);
+      }
+    }
+    return digest;
+  }
+
+ private:
+  uint64_t max_chunk_bytes_;
+};
+
+}  // namespace meshnet::worker
+
+#endif  // MESHNET_NATIVE_WORKER_FAKE_ENGINE_H_

packages/node/native/worker/shard_service.cpp

@@ -0,0 +1,364 @@
+#include "shard_service.h"
+
+#include <chrono>
+#include <utility>
+
+namespace meshnet::worker {
+
+namespace {
+
+int64_t NowUnixNanos() {
+  return std::chrono::duration_cast<std::chrono::nanoseconds>(
+             std::chrono::system_clock::now().time_since_epoch())
+      .count();
+}
+
+// Build the standard fail response (a terminal-or-not ShardStatus).
+sp::SessionResponse MakeFail(const std::string& route_session_id, const std::string& work_id,
+                             uint64_t step, sp::ErrorCode code, const std::string& detail,
+                             bool terminal, bool retryable) {
+  sp::SessionResponse response;
+  sp::ShardStatus* status = response.mutable_status();
+  status->set_work_id(work_id);
+  status->set_route_session_id(route_session_id);
+  status->set_idempotency_step(step);
+  status->set_terminal(terminal);
+  sp::ShardError* error = status->mutable_error();
+  error->set_code(code);
+  error->set_detail(detail);
+  error->set_retryable(retryable);
+  return response;
+}
+
+sp::SessionResponse MakeAck(const std::string& work_id, uint64_t step, bool duplicate) {
+  sp::SessionResponse response;
+  sp::Ack* ack = response.mutable_ack();
+  ack->set_work_id(work_id);
+  ack->set_idempotency_step(step);
+  ack->set_duplicate(duplicate);
+  return response;
+}
+
+void FillDefaultFlow(sp::FlowControl* fc, const FlowLimits& limits) {
+  fc->set_credits_granted(limits.credits_granted);
+  fc->set_max_inflight_chunks(limits.max_inflight_chunks);
+  fc->set_max_chunk_bytes(limits.max_chunk_bytes);
+  fc->set_max_prefill_chunk_tokens(limits.max_prefill_chunk_tokens);
+}
+
+}  // namespace
+
+grpc::Status ShardRuntimeServiceImpl::GetCapability(grpc::ServerContext*,
+                                                    const sp::CapabilityRequest*,
+                                                    sp::CapabilityReport* response) {
+  response->set_schema_version(sp::SCHEMA_VERSION_1);
+  sp::Fingerprint* fp = response->mutable_fingerprint();
+  fp->set_model_artifact_digest("sha256:native-test-artifact");
+  fp->set_runtime_recipe_digest("sha256:native-test-recipe");
+  fp->set_recipe_id("native-test");
+  fp->set_recipe_version("1");
+  fp->set_catalogue_version("1");
+  sp::ShardRange* range = response->mutable_shard_range();
+  range->set_start_layer(0);
+  range->set_end_layer(32);
+  range->set_effective_start_layer(0);
+  response->set_backend("grpc-native-cpp");
+  response->set_device("cpu");
+  response->set_validated(true);
+  response->set_detail("bounded real forward passed for fixture artifact");
+  response->set_max_concurrent_sessions(8);
+  response->set_max_context_tokens(131072);
+  FillDefaultFlow(response->mutable_flow_control(), limits_);
+  response->add_accepted_compression(sp::COMPRESSION_NONE);
+  response->add_supported_schema_versions(sp::SCHEMA_VERSION_1);
+  response->set_validated_at_unix_nanos(0);
+  return grpc::Status::OK;
+}
+
+grpc::Status ShardRuntimeServiceImpl::Health(grpc::ServerContext*, const sp::HealthRequest*,
+                                             sp::HealthReport* response) {
+  response->set_schema_version(sp::SCHEMA_VERSION_1);
+  response->set_state(sp::SERVING_STATE_SERVING);
+  response->set_active_sessions(1);
+  response->set_queued_chunks(0);
+  response->set_batch_occupancy(0);
+  response->set_kv_pressure(0.0f);
+  response->set_resident_bytes(0);
+  response->set_detail("native fixture worker serving");
+  return grpc::Status::OK;
+}
+
+uint32_t ShardRuntimeServiceImpl::MarkCancelled(const std::string& route_session_id,
+                                                const std::string& work_id) {
+  std::lock_guard<std::mutex> lk(sessions_mu_);
+  SessionState& state = sessions_[route_session_id];  // creates on first cancel-before-open
+  if (state.max_inflight == 0) {
+    // Freshly created placeholder for a Cancel that raced ahead of Open.
+    state.credits = limits_.credits_granted;
+    state.max_inflight = limits_.max_inflight_chunks;
+    state.max_chunk_bytes = limits_.max_chunk_bytes;
+  }
+  if (work_id.empty()) {
+    const bool already = state.cancelled_session;
+    state.cancelled_session = true;
+    return already ? 0 : 1;
+  }
+  const bool already = state.cancelled_work.count(work_id) != 0;
+  state.cancelled_work.insert(work_id);
+  return already ? 0 : 1;
+}
+
+grpc::Status ShardRuntimeServiceImpl::Session(
+    grpc::ServerContext*,
+    grpc::ServerReaderWriter<sp::SessionResponse, sp::SessionRequest>* stream) {
+  std::string route_session_id;
+  sp::SessionRequest request;
+
+  while (stream->Read(&request)) {
+    switch (request.kind_case()) {
+      case sp::SessionRequest::kOpen: {
+        const sp::SessionOpen& open = request.open();
+        route_session_id = open.route_session_id();
+        {
+          std::lock_guard<std::mutex> lk(sessions_mu_);
+          SessionState state;
+          state.epoch = open.route_epoch();
+          if (open.has_proposed_flow_control()) {
+            const sp::FlowControl& fc = open.proposed_flow_control();
+            state.credits = fc.credits_granted();
+            state.max_inflight = fc.max_inflight_chunks();
+            state.max_chunk_bytes = fc.max_chunk_bytes();
+          } else {
+            state.credits = limits_.credits_granted;
+            state.max_inflight = limits_.max_inflight_chunks;
+            state.max_chunk_bytes = limits_.max_chunk_bytes;
+          }
+          auto it = sessions_.find(route_session_id);
+          if (it != sessions_.end()) {
+            // A prior out-of-band Cancel may have marked this session cancelled
+            // before Open arrived; preserve that so the work still fails closed.
+            state.cancelled_session = it->second.cancelled_session;
+            state.cancelled_work = it->second.cancelled_work;
+          }
+          sessions_[route_session_id] = std::move(state);
+        }
+        sp::SessionResponse response;
+        sp::SessionAccepted* accepted = response.mutable_accepted();
+        accepted->set_schema_version(sp::SCHEMA_VERSION_1);
+        accepted->set_route_session_id(open.route_session_id());
+        accepted->set_route_epoch(open.route_epoch());
+        if (open.has_proposed_flow_control()) {
+          *accepted->mutable_flow_control() = open.proposed_flow_control();
+        } else {
+          FillDefaultFlow(accepted->mutable_flow_control(), limits_);
+        }
+        if (open.accepted_compression_size() > 0) {
+          for (int c : open.accepted_compression()) {
+            accepted->add_accepted_compression(static_cast<sp::Compression>(c));
+          }
+        } else {
+          accepted->add_accepted_compression(sp::COMPRESSION_NONE);
+        }
+        *accepted->mutable_fingerprint() = open.fingerprint();
+        stream->Write(response);
+        break;
+      }
+
+      case sp::SessionRequest::kChunk: {
+        const sp::ActivationChunk& chunk = request.chunk();
+        const sp::Envelope& envelope = chunk.envelope();
+        const std::string work_id = envelope.work_id();
+        const uint64_t step = envelope.idempotency_step();
+
+        // Compute the response under the lock, then write it *after* releasing —
+        // holding the lock across a (possibly blocking) Write would deadlock an
+        // out-of-band Cancel RPC that needs the same lock.
+        sp::SessionResponse response;
+        {
+          std::lock_guard<std::mutex> lk(sessions_mu_);
+          auto it = sessions_.find(route_session_id);
+          SessionState* state = it != sessions_.end() ? &it->second : nullptr;
+
+          if (state && (state->cancelled_session || state->cancelled_work.count(work_id))) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CANCELLED,
+                               "work was cancelled", false, false);
+          } else if (state && envelope.route_epoch() < state->epoch) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_EPOCH_STALE,
+                               "stale route epoch", false, false);
+          } else if (envelope.deadline_unix_nanos() != 0 &&
+                     NowUnixNanos() > envelope.deadline_unix_nanos()) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_DEADLINE_EXCEEDED,
+                               "deadline already passed", false, false);
+          } else if (state && state->seen_steps.count(step)) {
+            response = MakeAck(work_id, step, /*duplicate=*/true);
+          } else if (state && state->credits <= 0) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_FLOW_CONTROL_VIOLATION,
+                               "no flow-control credit remaining", false, true);
+          } else {
+            const BundleCheck check = engine_.Validate(chunk.bundle());
+            if (check.oversize_detail) {
+              response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_RESOURCE_EXHAUSTED,
+                                 *check.oversize_detail, false, false);
+            } else if (check.corrupt_detail) {
+              response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT,
+                                 *check.corrupt_detail, false, false);
+            } else {
+              if (state) {
+                state->seen_steps.insert(step);
+                state->credits -= 1;
+              }
+              engine_.BoundedForward(chunk.bundle());  // real bounded forward over wire bytes
+              *response.mutable_chunk() = chunk;  // echo the exact bundle back
+            }
+          }
+        }
+        stream->Write(response);
+        break;
+      }
+
+      case sp::SessionRequest::kDecode: {
+        const sp::DecodeStep& step_msg = request.decode();
+        const std::string work_id = step_msg.work_id();
+        const uint64_t step = step_msg.idempotency_step();
+
+        sp::TensorBundle bundle;
+        if (step_msg.bundle().tensors_size() > 0) {
+          bundle = step_msg.bundle();
+        } else {
+          bundle.set_bundle_version(1);
+          *bundle.add_tensors() = step_msg.tensor();
+        }
+
+        sp::SessionResponse response;
+        {
+          std::lock_guard<std::mutex> lk(sessions_mu_);
+          auto it = sessions_.find(route_session_id);
+          SessionState* state = it != sessions_.end() ? &it->second : nullptr;
+
+          if (state && (state->cancelled_session || state->cancelled_work.count(work_id))) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CANCELLED,
+                               "work was cancelled", false, false);
+          } else if (step_msg.deadline_unix_nanos() != 0 &&
+                     NowUnixNanos() > step_msg.deadline_unix_nanos()) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_DEADLINE_EXCEEDED,
+                               "deadline already passed", false, false);
+          } else if (state && state->seen_steps.count(step)) {
+            response = MakeAck(work_id, step, /*duplicate=*/true);
+          } else if (state && state->credits <= 0) {
+            response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_FLOW_CONTROL_VIOLATION,
+                               "no flow-control credit remaining", false, true);
+          } else {
+            const BundleCheck check = engine_.Validate(bundle);
+            if (check.oversize_detail) {
+              response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_RESOURCE_EXHAUSTED,
+                                 *check.oversize_detail, false, false);
+            } else if (check.corrupt_detail) {
+              response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT,
+                                 *check.corrupt_detail, false, false);
+            } else {
+              if (state) {
+                state->seen_steps.insert(step);
+                state->credits -= 1;
+              }
+              engine_.BoundedForward(bundle);
+              // No decode response field exists; echo the step back as a
+              // chunk-bearing SessionResponse per the proto's relayed-frame design.
+              sp::ActivationChunk* out = response.mutable_chunk();
+              sp::Envelope* out_env = out->mutable_envelope();
+              out_env->set_schema_version(sp::SCHEMA_VERSION_1);
+              out_env->set_work_id(work_id);
+              out_env->set_idempotency_step(step);
+              out_env->set_phase(sp::PHASE_DECODE);
+              sp::PositionSpan* pos = out_env->mutable_position();
+              pos->set_first_position(step_msg.position());
+              pos->set_token_count(1);
+              *out->mutable_bundle() = bundle;
+            }
+          }
+        }
+        stream->Write(response);
+        break;
+      }
+
+      case sp::SessionRequest::kFlowControl: {
+        const uint32_t topup = request.flow_control().credits_granted();
+        sp::SessionResponse response;
+        {
+          std::lock_guard<std::mutex> lk(sessions_mu_);
+          auto it = sessions_.find(route_session_id);
+          sp::FlowControl* fc = response.mutable_flow_control();
+          if (it != sessions_.end()) {
+            SessionState& state = it->second;
+            int64_t granted = std::min<int64_t>(state.credits + topup,
+                                                 static_cast<int64_t>(state.max_inflight));
+            state.credits = granted;
+            fc->set_credits_granted(static_cast<uint32_t>(granted));
+            fc->set_max_inflight_chunks(state.max_inflight);
+            fc->set_max_chunk_bytes(state.max_chunk_bytes);
+          } else {
+            fc->set_credits_granted(topup != 0 ? topup : limits_.credits_granted);
+            fc->set_max_inflight_chunks(limits_.max_inflight_chunks);
+            fc->set_max_chunk_bytes(limits_.max_chunk_bytes);
+          }
+          fc->set_max_prefill_chunk_tokens(limits_.max_prefill_chunk_tokens);
+        }
+        stream->Write(response);
+        break;
+      }
+
+      case sp::SessionRequest::kRelease: {
+        const sp::ReleaseSignal& release = request.release();
+        sp::SessionResponse response;
+        sp::ShardStatus* status = response.mutable_status();
+        status->set_work_id(release.work_id());
+        status->set_route_session_id(release.route_session_id());
+        status->set_terminal(true);
+        stream->Write(response);
+        return grpc::Status::OK;
+      }
+
+      case sp::SessionRequest::kCancel: {
+        const sp::CancelSignal& signal = request.cancel();
+        MarkCancelled(route_session_id, signal.work_id());
+        const bool whole_session = signal.work_id().empty();
+        stream->Write(MakeFail(route_session_id, signal.work_id(), 0, sp::ERROR_CODE_CANCELLED,
+                               signal.reason().empty() ? "cancelled" : signal.reason(),
+                               whole_session, false));
+        if (whole_session) {
+          return grpc::Status::OK;
+        }
+        break;
+      }
+
+      default: {
+        sp::SessionResponse response;
+        response.mutable_status()->set_terminal(true);
+        stream->Write(response);
+        return grpc::Status::OK;
+      }
+    }
+  }
+  return grpc::Status::OK;
+}
+
+grpc::Status ShardRuntimeServiceImpl::Release(grpc::ServerContext*,
+                                              const sp::ReleaseRequest* request,
+                                              sp::ReleaseResponse* response) {
+  bool existed;
+  {
+    std::lock_guard<std::mutex> lk(sessions_mu_);
+    existed = sessions_.erase(request->route_session_id()) != 0;
+  }
+  response->set_released(existed);
+  return grpc::Status::OK;
+}
+
+grpc::Status ShardRuntimeServiceImpl::Cancel(grpc::ServerContext*,
+                                             const sp::CancelRequest* request,
+                                             sp::CancelResponse* response) {
+  const uint32_t newly = MarkCancelled(request->route_session_id(), request->work_id());
+  response->set_cancelled_work_items(newly);
+  return grpc::Status::OK;
+}
+
+}  // namespace meshnet::worker

packages/node/native/worker/shard_service.h

@@ -0,0 +1,85 @@
+// The native Shard worker's ShardRuntime service (DGR-033).
+//
+// A faithful C++ port of `ShardRuntimeServicer` in `shard_runtime_server.py`:
+// the same per-`route_session_id` identity/credit/dedup state, the same
+// fail-closed negative paths (stale epoch, expired deadline, corrupt/oversize
+// payload, exhausted flow-control credit, duplicate idempotency step, in-band
+// and out-of-band cancellation), and the same lifecycle (open/prefill/decode/
+// flow-control/release/cancel). The only compute it does is the fake engine's
+// bounded forward — there is no llama.cpp linkage and no arbitrary-graph RPC.
+
+#ifndef MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_
+#define MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_
+
+#include <cstdint>
+#include <map>
+#include <mutex>
+#include <set>
+#include <string>
+
+#include <grpcpp/grpcpp.h>
+
+#include "fake_engine.h"
+#include "shard_runtime.grpc.pb.h"
+#include "shard_runtime.pb.h"
+
+namespace meshnet::worker {
+
+namespace sp = ::meshnet::shard::v1;
+
+struct FlowLimits {
+  uint32_t credits_granted = 16;
+  uint32_t max_inflight_chunks = 16;
+  uint64_t max_chunk_bytes = 4u * 1024u * 1024u;
+  uint32_t max_prefill_chunk_tokens = 512;
+};
+
+// Per-route-session identity/credit/dedup state, kept on the servicer instance
+// (guarded by a lock) so an out-of-band unary Cancel from a different handler
+// thread can reach a session a concurrent Session stream is still iterating.
+struct SessionState {
+  uint64_t epoch = 0;
+  int64_t credits = 0;
+  uint32_t max_inflight = 0;
+  uint64_t max_chunk_bytes = 0;
+  std::set<uint64_t> seen_steps;
+  std::set<std::string> cancelled_work;
+  bool cancelled_session = false;
+};
+
+class ShardRuntimeServiceImpl final : public sp::ShardRuntime::Service {
+ public:
+  explicit ShardRuntimeServiceImpl(FlowLimits limits)
+      : limits_(limits), engine_(limits.max_chunk_bytes) {}
+
+  grpc::Status GetCapability(grpc::ServerContext* context,
+                             const sp::CapabilityRequest* request,
+                             sp::CapabilityReport* response) override;
+
+  grpc::Status Health(grpc::ServerContext* context, const sp::HealthRequest* request,
+                      sp::HealthReport* response) override;
+
+  grpc::Status Session(
+      grpc::ServerContext* context,
+      grpc::ServerReaderWriter<sp::SessionResponse, sp::SessionRequest>* stream) override;
+
+  grpc::Status Release(grpc::ServerContext* context, const sp::ReleaseRequest* request,
+                       sp::ReleaseResponse* response) override;
+
+  grpc::Status Cancel(grpc::ServerContext* context, const sp::CancelRequest* request,
+                      sp::CancelResponse* response) override;
+
+ private:
+  // Returns the number of items newly marked cancelled, creating session state
+  // if the Cancel raced ahead of SessionOpen.
+  uint32_t MarkCancelled(const std::string& route_session_id, const std::string& work_id);
+
+  FlowLimits limits_;
+  FakeShardEngine engine_;
+  std::mutex sessions_mu_;
+  std::map<std::string, SessionState> sessions_;
+};
+
+}  // namespace meshnet::worker
+
+#endif  // MESHNET_NATIVE_WORKER_SHARD_SERVICE_H_

packages/node/native/worker/shard_worker_main.cpp

@@ -0,0 +1,302 @@
+// Standalone native Shard worker executable (DGR-033).
+//
+// Serves the complete ShardRuntime lifecycle/stream contract over real
+// gRPC/HTTP2 using the model-free FakeShardEngine. It links neither llama.cpp
+// nor any graph-execution entry point: the only surface it exposes is the
+// ShardRuntime service defined in shard_runtime.proto.
+//
+// Usage:
+//   shard_worker [listen_addr]     serve until SIGTERM/SIGINT (graceful drain)
+//   shard_worker --selftest        bind an ephemeral port, self-drive the
+//                                  lifecycle over a real loopback channel, exit
+//
+// Environment:
+//   MESHNET_SHARD_LISTEN_ADDR   host:port to bind (default localhost:50051)
+//   MESHNET_MAX_CHUNK_BYTES     per-chunk byte ceiling the worker enforces
+//
+// On a normal run it prints one readiness line — "ShardRuntime worker listening
+// on <addr>" — once the socket is bound, so a supervisor/harness has a real
+// readiness signal instead of a sleep.
+
+#include <atomic>
+#include <cerrno>
+#include <csignal>
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <thread>
+#include <unistd.h>
+
+#include <grpcpp/grpcpp.h>
+
+#include "shard_service.h"
+#include "shard_runtime.grpc.pb.h"
+
+namespace {
+
+namespace sp = ::meshnet::shard::v1;
+
+// Self-pipe: the signal handler must stay async-signal-safe, so it only writes
+// one byte; a helper thread reads it and performs the (non-signal-safe) server
+// Shutdown(). Set once in main() before installing the handler.
+volatile std::sig_atomic_t g_signal_pipe_write_fd = -1;
+
+extern "C" void HandleTermination(int /*signum*/) {
+  if (g_signal_pipe_write_fd >= 0) {
+    const char byte = 1;
+    ssize_t rc = ::write(g_signal_pipe_write_fd, &byte, 1);
+    (void)rc;  // best-effort; nothing safe to do on failure inside a handler
+  }
+}
+
+meshnet::worker::FlowLimits LimitsFromEnv() {
+  meshnet::worker::FlowLimits limits;
+  if (const char* raw = std::getenv("MESHNET_MAX_CHUNK_BYTES")) {
+    char* end = nullptr;
+    const unsigned long long value = std::strtoull(raw, &end, 10);
+    if (end != raw && value > 0) {
+      limits.max_chunk_bytes = static_cast<uint64_t>(value);
+    }
+  }
+  return limits;
+}
+
+int RunSelfTest() {
+  meshnet::worker::ShardRuntimeServiceImpl service(LimitsFromEnv());
+  int selected_port = 0;
+  grpc::ServerBuilder builder;
+  builder.AddListeningPort("127.0.0.1:0", grpc::InsecureServerCredentials(), &selected_port);
+  builder.RegisterService(&service);
+  std::unique_ptr<grpc::Server> server(builder.BuildAndStart());
+  if (!server || selected_port == 0) {
+    std::cerr << "selftest: failed to bind ephemeral port\n";
+    return 1;
+  }
+  const std::string target = "127.0.0.1:" + std::to_string(selected_port);
+  auto channel = grpc::CreateChannel(target, grpc::InsecureChannelCredentials());
+  auto stub = sp::ShardRuntime::NewStub(channel);
+
+  int failures = 0;
+  auto check = [&](bool cond, const char* what) {
+    if (!cond) {
+      std::cerr << "selftest FAIL: " << what << "\n";
+      ++failures;
+    }
+  };
+
+  // Capability + health.
+  {
+    grpc::ClientContext ctx;
+    sp::CapabilityRequest req;
+    req.set_schema_version(sp::SCHEMA_VERSION_1);
+    sp::CapabilityReport rep;
+    grpc::Status status = stub->GetCapability(&ctx, req, &rep);
+    check(status.ok(), "GetCapability RPC");
+    check(rep.validated(), "capability validated");
+    check(rep.schema_version() == sp::SCHEMA_VERSION_1, "capability schema version");
+  }
+  {
+    grpc::ClientContext ctx;
+    sp::HealthRequest req;
+    req.set_schema_version(sp::SCHEMA_VERSION_1);
+    sp::HealthReport rep;
+    grpc::Status status = stub->Health(&ctx, req, &rep);
+    check(status.ok(), "Health RPC");
+    check(rep.state() == sp::SERVING_STATE_SERVING, "health serving");
+  }
+
+  // A minimal session: open -> fragmented prefill -> decode -> release.
+  {
+    grpc::ClientContext ctx;
+    auto stream = stub->Session(&ctx);
+
+    sp::SessionRequest open;
+    sp::SessionOpen* o = open.mutable_open();
+    o->set_schema_version(sp::SCHEMA_VERSION_1);
+    o->set_route_session_id("selftest");
+    o->set_route_epoch(1);
+    sp::FlowControl* fc = o->mutable_proposed_flow_control();
+    fc->set_credits_granted(16);
+    fc->set_max_inflight_chunks(16);
+    fc->set_max_chunk_bytes(4u * 1024u * 1024u);
+    check(stream->Write(open), "write open");
+
+    sp::SessionResponse accepted;
+    check(stream->Read(&accepted), "read accepted");
+    check(accepted.kind_case() == sp::SessionResponse::kAccepted, "accepted kind");
+
+    // Fragmented prefill: two fragments tiling a 6-byte payload.
+    const std::string payload = "ABCDEF";
+    sp::SessionRequest chunk;
+    sp::ActivationChunk* ac = chunk.mutable_chunk();
+    sp::Envelope* env = ac->mutable_envelope();
+    env->set_schema_version(sp::SCHEMA_VERSION_1);
+    env->set_work_id("w1");
+    env->set_route_session_id("selftest");
+    env->set_route_epoch(1);
+    env->set_idempotency_step(1);
+    env->set_phase(sp::PHASE_PREFILL);
+    sp::TensorBundle* bundle = ac->mutable_bundle();
+    bundle->set_bundle_version(1);
+    sp::NamedTensor* tensor = bundle->add_tensors();
+    tensor->set_name("hidden_states");
+    tensor->set_dtype(sp::DTYPE_BFLOAT16);
+    tensor->set_byte_order(sp::BYTE_ORDER_LITTLE_ENDIAN);
+    tensor->set_total_bytes(payload.size());
+    tensor->set_compression(sp::COMPRESSION_NONE);
+    sp::Checksum* cksum = tensor->mutable_checksum();
+    cksum->set_algorithm(sp::CHECKSUM_ALGORITHM_CRC32C);
+    const uint32_t crc = meshnet::worker::Crc32(payload);
+    std::string crc_be(4, '\0');
+    crc_be[0] = static_cast<char>((crc >> 24) & 0xFF);
+    crc_be[1] = static_cast<char>((crc >> 16) & 0xFF);
+    crc_be[2] = static_cast<char>((crc >> 8) & 0xFF);
+    crc_be[3] = static_cast<char>(crc & 0xFF);
+    cksum->set_value(crc_be);
+    sp::TensorFragment* f0 = tensor->add_fragments();
+    f0->set_fragment_index(0);
+    f0->set_fragment_count(2);
+    f0->set_byte_offset(0);
+    f0->set_payload(payload.substr(0, 3));
+    sp::TensorFragment* f1 = tensor->add_fragments();
+    f1->set_fragment_index(1);
+    f1->set_fragment_count(2);
+    f1->set_byte_offset(3);
+    f1->set_payload(payload.substr(3));
+    check(stream->Write(chunk), "write chunk");
+
+    sp::SessionResponse echoed;
+    check(stream->Read(&echoed), "read chunk echo");
+    check(echoed.kind_case() == sp::SessionResponse::kChunk, "chunk echo kind");
+
+    sp::SessionRequest decode;
+    sp::DecodeStep* ds = decode.mutable_decode();
+    ds->set_idempotency_step(2);
+    ds->set_position(1);
+    ds->set_work_id("w2");
+    sp::TensorBundle* dbundle = ds->mutable_bundle();
+    dbundle->set_bundle_version(1);
+    sp::NamedTensor* dt = dbundle->add_tensors();
+    dt->set_name("hidden_states");
+    dt->set_dtype(sp::DTYPE_BFLOAT16);
+    dt->set_byte_order(sp::BYTE_ORDER_LITTLE_ENDIAN);
+    dt->set_total_bytes(payload.size());
+    dt->set_compression(sp::COMPRESSION_NONE);
+    sp::Checksum* dck = dt->mutable_checksum();
+    dck->set_algorithm(sp::CHECKSUM_ALGORITHM_CRC32C);
+    dck->set_value(crc_be);
+    sp::TensorFragment* df = dt->add_fragments();
+    df->set_fragment_index(0);
+    df->set_fragment_count(1);
+    df->set_byte_offset(0);
+    df->set_payload(payload);
+    check(stream->Write(decode), "write decode");
+
+    sp::SessionResponse decode_echo;
+    check(stream->Read(&decode_echo), "read decode echo");
+    check(decode_echo.kind_case() == sp::SessionResponse::kChunk, "decode echo kind");
+
+    sp::SessionRequest release;
+    sp::ReleaseSignal* rs = release.mutable_release();
+    rs->set_route_session_id("selftest");
+    rs->set_work_id("w-final");
+    check(stream->Write(release), "write release");
+    stream->WritesDone();
+
+    sp::SessionResponse terminal;
+    check(stream->Read(&terminal), "read terminal");
+    check(terminal.kind_case() == sp::SessionResponse::kStatus && terminal.status().terminal(),
+          "terminal status");
+
+    grpc::Status status = stream->Finish();
+    check(status.ok(), "stream finish");
+  }
+
+  server->Shutdown();
+  server->Wait();
+
+  if (failures == 0) {
+    std::cout << "selftest: all lifecycle checks passed\n";
+    return 0;
+  }
+  std::cerr << "selftest: " << failures << " check(s) failed\n";
+  return 1;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+  GOOGLE_PROTOBUF_VERIFY_VERSION;
+
+  for (int i = 1; i < argc; ++i) {
+    if (std::strcmp(argv[i], "--selftest") == 0) {
+      return RunSelfTest();
+    }
+  }
+
+  std::string listen_addr = "localhost:50051";
+  if (const char* env = std::getenv("MESHNET_SHARD_LISTEN_ADDR")) {
+    listen_addr = env;
+  }
+  if (argc > 1 && argv[1][0] != '-') {
+    listen_addr = argv[1];
+  }
+
+  meshnet::worker::FlowLimits limits = LimitsFromEnv();
+  meshnet::worker::ShardRuntimeServiceImpl service(limits);
+
+  grpc::ServerBuilder builder;
+  int selected_port = 0;
+  builder.AddListeningPort(listen_addr, grpc::InsecureServerCredentials(), &selected_port);
+  // Bounded messages, two layers: a hard transport receive ceiling (never below
+  // 4 MiB so the handshake and normal chunks always fit) plus the finer
+  // app-level per-tensor RESOURCE_EXHAUSTED check the service enforces against
+  // the negotiated max_chunk_bytes. Neither path lets an unbounded frame in.
+  constexpr int kTransportFloor = 4 * 1024 * 1024;
+  const int transport_max = limits.max_chunk_bytes > static_cast<uint64_t>(kTransportFloor)
+                                ? static_cast<int>(limits.max_chunk_bytes)
+                                : kTransportFloor;
+  builder.SetMaxReceiveMessageSize(transport_max);
+  builder.RegisterService(&service);
+  std::unique_ptr<grpc::Server> server(builder.BuildAndStart());
+  if (!server || selected_port == 0) {
+    std::cerr << "failed to bind " << listen_addr << "\n";
+    return 1;
+  }
+
+  int pipe_fds[2];
+  if (::pipe(pipe_fds) != 0) {
+    std::cerr << "failed to create shutdown pipe\n";
+    return 1;
+  }
+  g_signal_pipe_write_fd = pipe_fds[1];
+
+  struct sigaction sa;
+  std::memset(&sa, 0, sizeof(sa));
+  sa.sa_handler = HandleTermination;
+  ::sigaction(SIGTERM, &sa, nullptr);
+  ::sigaction(SIGINT, &sa, nullptr);
+
+  // Drain thread: wakes on the first termination signal and shuts the server
+  // down gracefully so in-flight sessions finish rather than being severed.
+  std::thread drain([&server, read_fd = pipe_fds[0]]() {
+    char byte = 0;
+    ssize_t rc = 0;
+    do {
+      rc = ::read(read_fd, &byte, 1);
+    } while (rc < 0 && errno == EINTR);
+    server->Shutdown();
+  });
+
+  std::cout << "ShardRuntime worker listening on " << listen_addr << std::endl;
+
+  server->Wait();
+  drain.join();
+  ::close(pipe_fds[0]);
+  ::close(pipe_fds[1]);
+  std::cout << "ShardRuntime worker shut down cleanly" << std::endl;
+  return 0;
+}