# 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

```bash
pytest -q tests/test_activation_envelope.py
```

```text
5 passed in 0.06s
```

```bash
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'
```

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

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

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

```bash
git diff --check
```

```text
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.