popov/neuron-tai
1
0
Fork 0
Code Issues 42 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add activation stream envelope

Browse Source
This commit is contained in:
Dobromir Popov
2026-07-17 02:36:24 +03:00
parent 989b55970b
commit ab466ce6b6
7 changed files with 674 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md Normal file
View File

@@ -0,0 +1,101 @@
# 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.

10
.scratch/distributed-gguf-runtime/gitea-issues.json
View File

@@ -28,20 +28,20 @@
"DGR-021": {
"number": 5,
"url": "https://git.d-popov.com/popov/neuron-tai/issues/5",
"state": "open",
"status": "ready"
"state": "closed",
"status": "completed"
},
"DGR-022": {
"number": 6,
"url": "https://git.d-popov.com/popov/neuron-tai/issues/6",
"state": "open",
"status": "blocked"
"status": "ready"
},
"DGR-023": {
"number": 7,
"url": "https://git.d-popov.com/popov/neuron-tai/issues/7",
"state": "open",
"status": "blocked"
"status": "ready"
},
"DGR-024": {
"number": 8,
@@ -53,7 +53,7 @@
"number": 9,
"url": "https://git.d-popov.com/popov/neuron-tai/issues/9",
"state": "open",
"status": "blocked"
"status": "ready"
},
"DGR-026": {
"number": 10,

14
.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md
View File

@@ -1,7 +1,7 @@
<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
# DGR-021: Define the versioned named-tensor stream envelope
- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
- **Status / triage:** completed; `passes: true`
- **Execution mode:** `AFK`
- **Milestone:** `M1`
- **Dependencies:** `DGR-018`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
## Acceptance criteria
- [ ] Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.
- [ ] Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.
- [ ] Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.
- [ ] Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.
- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
- [x] Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.
- [x] Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.
- [x] Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.
- [x] Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.
- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
## Shared quality gates
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
## Evidence handoff
Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

3
.scratch/distributed-gguf-runtime/prd.json
View File

@@ -441,7 +441,8 @@
"Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.",
"Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
],
"passes": false,
"passes": true,
"completionNotes": "Added a versioned activation envelope with deterministic JSON serialization, bounded tensor fragmentation, checksum validation, unknown-field preservation, and TensorPayload conversion hooks; verified by targeted pytest and compileall runs.",
"notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md; prd.json is authoritative.",
"blocks": [
"DGR-022",