# OpenSpec Change: network-plugin-protocol

- **Change ID**: network-plugin-protocol
- **Package**: `@suaveplan/network-plugin-protocol` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

The tiered network needs a compact, versioned binary protocol for all messages between peers. The genesis `bitpacker` package provides the binary serialization, and `serialize` provides schemas. This plugin implements a 13-byte header + binary payload format that replaces the suaveplan `network-protocol` stub. It integrates with the `streams` transforms for real encryption, compression, and framing.

## What changes

- **ADDED**: `ProtocolPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `BinaryProtocol` — 13-byte header: `version(1) | flags(1) | messageType(1) | timestamp(8) | payloadLength(2)`.
- **ADDED**: `MessageEncoder` / `MessageDecoder` — schema-aware encoding/decoding using `@suaveplan/bitpacker`.
- **ADDED**: `ProtocolPipeline` — wires `lengthPrefixEncode` → `CryptoTransform` → `compressStream` for outgoing, and reverse for incoming.
- **ADDED**: `FastPathDispatcher` — zero-copy fast path for common message types (heartbeat, ping, registry delta). Bypasses full pipeline when message type is in the fast-path allowlist and no encryption/compression is required.
- **ADDED**: `NETWORK_PROTO_CODES` — frozen error registry.

## Out of scope

- Protocol negotiation / version handshake → future `network-plugin-protocol-negotiation`.
- Custom message types beyond registry/governance/topology/failover → future plugins register their own.

## Source mapping

This change derives from `../suaveplan/enterprise/network-protocol.md` and `../suaveplan/packages/universal/network-protocol/`.

| Requirement | Source lines | Notes |
|---|---|---|
| 13-byte binary header | `network-protocol/README.md` §Binary Protocol | verbatim |
| Version, flags, messageType, timestamp, payloadLength | `network-protocol/README.md` §Binary Protocol | verbatim |
| Schema-aware encoding | `network-protocol/README.md` §Message Encoder/Decoder | reworded; uses `@suaveplan/bitpacker` |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `ProtocolPipeline` using `streams` transforms | Genesis has real crypto/compression/framing; protocol should use them |
| `ProtocolPlugin` implements `NetworkPlugin` | Required to plug into `NetworkNode` |

## Verification approach

- `src/protocol/protocol.spec-conformance.test.ts` — pins header format, version, flags.
- `src/encoder/encoder.spec-conformance.test.ts` — pins schema encoding, roundtrip.
- `src/pipeline/pipeline.spec-conformance.test.ts` — pins pipeline ordering, error handling.
- `tests/dep-graph.test.ts` — pins direct import of `@suaveplan/bitpacker`, `@suaveplan/streams`.

## Enhancement: Serialization Strategy Framework

**Source**: `docs/old-network-planning/PHASE_9.md` §Serialization Strategies

The protocol plugin currently assumes a single binary encoding. The old docs defined multiple serialization strategies with a factory pattern:

- **JSON Serializer** — human-readable, widely compatible
- **Binary Serializer** — compact, schema-based, optional compression
- **MessagePack Serializer** — compact binary with extensions
- **Protocol Buffers Serializer** — schema-based with versioning
- **SerializerFactory** — selects serializer by content type with fallback

**Added to this change**:

- `SerializerFactory` — registers serializers by content type, returns default on unknown.
- `JsonSerializer`, `BinarySerializer`, `MessagePackSerializer` — implement `ISerializer`.
- Content-type negotiation in 13-byte header flags.

## Enhancement: Message Priority Queue & Adaptive Batching

**Source**: `docs/old-network-planning/PHASE_3.md` §PriorityMessageQueue, `DESCRIPTION.md` §Adaptive Batching

The protocol needs explicit message queueing and batching:

- `PriorityMessageQueue` — multiple internal queues (one per priority tier). FIFO within same tier. CRITICAL messages bypass queue.
- `MessageBatcher` — groups related messages by type/recipient. Flushes on size, time, or priority trigger. Adaptive interval based on network conditions.
- `BackpressureController` — detects overwhelmed downstream and slows production.

## Enhancement: Message TTL & Loop Detection

**Source**: `docs/old-network-planning/PHASE_3.md` §Message Expiration

- `MessageTTL` — time-to-live in hops. Drops message when `ttl <= 0`.
- `LoopDetector` — tracks `visitedNodes` in envelope header. Drops on cycle detection.
- `DuplicateDetector` — deduplicates broadcast messages via `messageId` + bloom filter.

## Enhancement: Route Caching

**Source**: `docs/old-network-planning/PHASE_3.md` §Route Caching

- `RouteCache` — caches frequently used `(source, target) → nextHop` mappings.
- Cache invalidation on `topology:changed` bus event.
- Adaptive cache size based on memory availability.

## Migration impact

None — additive only.