neuron-tai/.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md

DGR-042 evidence — native frames through direct and relay seams

Date: 2026-08-01
Authority: .scratch/distributed-gguf-runtime/prd.json.

Implemented

• Added NativeActivationSeam, a Route-Session-scoped adapter with exactly two selectable transports. Direct traffic calls the generated ShardRuntimeStub.Session() once and keeps its bidirectional gRPC stream open for the session. Its request and response hand-off queues are bounded.
• Relay traffic calls the existing persistent relay request shape with POST /native/session, application/x-protobuf, and the exact SessionRequest.SerializeToString() body. It parses only the returned SessionResponse; neither the adapter nor the relay contract rewrites a protobuf frame. Relay failure is explicitly uncertain and is never retried.
• NativeFrameContext validates Route Session, epoch, work, and deadline fields against the versioned protobuf request before either path sends it. The unchanged existing relay header contract receives request/billing ID, node attribution, route, work, and deadline copies for control-plane telemetry/billing correlation. NativeSeamTelemetry reports per-node, per-request seam byte/latency observations without interpreting frames.
• Deterministic fake-worker tests cover a single direct stream, byte-identical relay request frames, relay disconnect/no replay, cancellation, correlation headers, telemetry, and bounded direct buffering.

Changed files

• packages/node/meshnet_node/native_activation_seam.py
• tests/test_native_activation_seam.py
• .scratch/distributed-gguf-runtime/prd.json
• .scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md
• .scratch/distributed-gguf-runtime/evidence/DGR-042/README.md
• .ralph-tui/progress.md

Commands and results

PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
  tests/test_native_activation_seam.py tests/test_native_shard_protocol.py \
  tests/test_native_worker_supervisor.py tests/test_native_registration.py \
  tests/test_ralph_prd_schema.py
# 172 passed, 2 skipped in 2.01s

/home/popov/.hermes/hermes-agent/venv/bin/python -m ruff check \
  packages/node/meshnet_node/native_activation_seam.py tests/test_native_activation_seam.py
# All checks passed!

python3 -m compileall -q packages tests
# exit 0

git diff --check
# exit 0

No model download, GPU, API credit, native worker build, or upstream patch was required. Native CMake/CTest and patch-stack gates do not apply to this Python-only transport adapter.

Limitations and dependency handoff

• Relay is deliberately a sequence of opaque existing relay RPC bodies, not a gRPC tunnel. The direct path alone is a long-lived gRPC stream; this avoids changing relay behavior while preserving native frame bytes.
• This fixture lane uses an injected generated-stub-shaped fake worker and an injected existing-relay-client-shaped callable. DGR-054/DGR-058 must use the adapter with certified workers and add real route-loss/restart policy; they must retain the no-replay rule after an uncertain relay send.
• DGR-024 supplied the versioned generated Session protocol and the prior raw-frame identity proof. DGR-040 supplied the verified worker lifecycle; its published native listen address is the direct endpoint for this seam.
• Existing Transformer HTTP routes and relay routing, load balancing, billing, and peer behavior were not changed.