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.

4.9 KiB Raw Blame History