102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# 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.
|