story: DGR-042 Carry native frames through direct and existing relay seams

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

@@ -0,0 +1,73 @@
+# 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
+
+```bash
+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.