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

DGR-021 evidence — versioned named-tensor activation envelope

Completed: 2026-07-17 Branch: distributed-gguf-runtime Authority: .scratch/distributed-gguf-runtime/prd.json Dependency: DGR-018 (evidence/DGR-018/README.md) — canonical backlog schema / issue projection contract

Objective

Establish the backend-neutral activation envelope used by direct and relayed Shard traffic, with stable versioning, named tensors, bounded fragmentation, checksum validation, and reserved extensibility for future state.

Changes

packages/node/meshnet_node/protocol.py (new)

Added a self-contained activation-envelope module with:

• SCHEMA_NAME = "meshnet.activation-stream" and SCHEMA_VERSION = 1
• TensorFragment
  • bounded byte fragments with offset, compression tag, checksum, and extension preservation
  • deterministic to_dict() / from_dict() round-trip
• NamedTensor
  • named tensor metadata: name, shape, dtype, byte_order, compression, checksum, fragments
  • fragmentation via from_bytes(..., max_fragment_bytes=...)
  • checksum validation over reconstructed tensor bytes
  • unknown-field preservation via extensions
• ActivationEnvelope
  • top-level fields for request_id, work_id, route_session, route_epoch, shard_start, effective_start, phase, position, and idempotency_step
  • reserved extension fields for token_id_sideband, architecture_state, recurrent_state, and mtp
  • deterministic canonical serialization (to_bytes) and round-trip parsing (from_bytes)
  • size-limit enforcement (to_bytes(max_bytes=...))
  • conversion from a live TensorPayload into the envelope and back again

packages/node/meshnet_node/model_backend.py

Extended TensorPayload with envelope conversion helpers:

• TensorPayload.to_envelope(...)
• TensorPayload.from_envelope(...)

These keep the existing activation payload interface intact while exposing the new versioned envelope as the shared protocol layer.

tests/test_activation_envelope.py (new)

Added focused deterministic tests covering:

• deterministic envelope serialization and round-trip parsing
• tensor fragmentation and checksum validation
• unknown-field preservation at both envelope and tensor levels
• size-limit rejection
• TensorPayload ↔ envelope round-trip

.scratch/distributed-gguf-runtime/prd.json

Marked DGR-021.passes = true and added completion notes recording the envelope implementation and verification commands.

Commands and results

pytest -q tests/test_activation_envelope.py

5 passed in 0.06s

pytest -q tests/test_activation_envelope.py tests/test_kv_cache_distributed.py -k 'session_is_stable_and_decode_payloads_are_single_token or large_prefill_activation_survives_zstd_compressed_hop'

..                                                                       [100%]
2 passed, 21 deselected in 1.84s

python3 -m compileall packages/node/meshnet_node tests/test_activation_envelope.py

Listing 'packages/node/meshnet_node'...
Listing 'packages/node/meshnet_node/native_protocol'...
Compiling 'tests/test_activation_envelope.py'...

git diff --check

No whitespace errors

Limitations

• The envelope is implemented as a canonical deterministic JSON contract with dataclasses and conversion hooks, not generated .proto classes. The environment had protobuf available but not the grpc_tools generation toolchain, so I did not materialize a compiled proto artifact here.
• The direct/relayed HTTP/WebSocket transports remain byte-oriented; the envelope is the shared structured contract layered above those transports.

Dependency handoff

DGR-022 and later shard-control stories can reuse the envelope contract and its TensorPayload conversion hooks as the stable activation metadata layer. Future work that requires generated protobuf code can replace the JSON serialization with a generated wire codec without changing the top-level field contract defined here.