first commit

docs/networking/network/network-plugin-registry/src/encoder/encoder.md

@@ -0,0 +1,46 @@
+# BinaryMessageEncoder
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Packs `PeerEntry` objects into compact binary format using `@suaveplan/bitpacker`. The encoded format is designed to fit within 62 bytes for efficient wire transmission. This encoder replaces verbose JSON representations with a tight binary schema, reducing bandwidth and parsing overhead in high-frequency mesh updates.
+
+## Features
+
+- Bitpacker schema for structured peer data
+- 62-byte size limit enforcement
+- Tier, latency, and address encoding
+- Roundtrip encoding and decoding
+- Automatic latency clamping to 16-bit maximum
+- UTF-8 peer ID and address encoding
+
+## Usage
+
+### Basic Example
+
+```ts
+import { BinaryMessageEncoder } from "@suaveplan/network-plugin-registry";
+
+const encoder = new BinaryMessageEncoder();
+const bytes = encoder.encode(peer);
+```
+
+### Advanced Example
+
+```ts
+import { BinaryMessageEncoder } from "@suaveplan/network-plugin-registry";
+
+const encoder = new BinaryMessageEncoder();
+const decoded = encoder.decode(bytes);
+```
+
+## API Reference
+
+- `encode(peer): Uint8Array` — pack peer into binary
+- `decode(data): PeerEntry` — unpack peer from binary
+
+## Implementation Notes
+
+The schema encodes tier as 8 bits, latency as 16 bits, and address length as 8 bits. The peer ID is encoded as UTF-8 bytes. Total payload must not exceed 62 bytes; larger payloads throw `INVALID_PEER_DATA`. Latency is clamped to 65535ms to fit the 16-bit field. The address length field allows variable-length addresses without delimiter overhead. Decoding strips null padding from the peer ID field so that fixed-width IDs do not leak trailing zeros into the string representation. The encoder is stateless and safe to reuse across many peers without re-instantiation. Because the encoder is pure, it can be shared between multiple registry instances or used in worker threads without synchronization concerns.