first commit

docs/networking/network/network-plugin-registry/README.md

@@ -0,0 +1,72 @@
+# @suaveplan/network-plugin-registry - Fixed-capacity peer registry with bitpacker-based binary message encoding
+
+## Summary
+
+Fixed-capacity peer registry with bitpacker-based binary encoding.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures withi…
+- [registry-plugin](./src/registry-plugin.md) — Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the…
+<!-- end:auto-docs -->  - [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures withi…
+- [registry-plugin](./src/registry-plugin.md) — Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the…
+- [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures withi…
+- [registry-plugin](./src/registry-plugin.md) — Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the…
+- [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures withi…
+- [registry-plugin](./src/registry-plugin.md) — Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the…
+- [encoder](./src/encoder/encoder.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_  - [registry](./src/registry/registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sync](./src/sync/sync.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures withi…
+- [registry-plugin](./src/registry-plugin.md) — Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the…
+
+## Purpose
+
+Manages a small, fixed-capacity registry of mesh peers. Provides CRUD operations, compact binary encoding via `@suaveplan/bitpacker`, and periodic sync to the network bus. This plugin is essential for mesh membership tracking and peer discovery.
+
+## Features
+
+- **Registry** — fixed-capacity peer storage with add/remove/get/list
+- **BinaryMessageEncoder** — bitpacker-based encoding, target ≤ 62 bytes
+- **RegistrySyncManager** — periodic `registry:update` bus events
+- **RegistryPlugin** — integrates everything into `NetworkNode`
+
+## Usage
+
+### Basic Example
+
+```ts
+import { RegistryPlugin } from "@suaveplan/network-plugin-registry";
+
+const plugin = new RegistryPlugin(32);
+node.use(plugin);
+plugin.registry.add({ peerId: "p1", address: "10.0.0.1", tier: 1, latencyMs: 5 });
+```
+
+### Advanced Example
+
+```ts
+import { Registry, BinaryMessageEncoder } from "@suaveplan/network-plugin-registry";
+
+const registry = new Registry(16);
+const encoder = new BinaryMessageEncoder();
+registry.add(peer);
+const bytes = encoder.encode(peer);
+```
+
+## API Reference
+
+See per-module documentation in `src/`:
+
+- `src/registry/` — `Registry`, `PeerEntry`
+- `src/encoder/` — `BinaryMessageEncoder`
+- `src/sync/` — `RegistrySyncManager`
+- `src/registry-plugin.ts` — `RegistryPlugin`
+
+## Implementation Notes
+
+The registry uses a `Map` for O(1) operations. Capacity is strictly enforced. The binary encoder uses a `@suaveplan/bitpacker` schema for tier (8 bits), latency (16 bits), and address length (8 bits). The 62-byte limit ensures registry messages are small enough for high-frequency updates.

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.

docs/networking/network/network-plugin-registry/src/error-codes.md

@@ -0,0 +1,51 @@
+# Registry Error Codes
+
+## Purpose
+
+Defines the stable error-code registry for the `@suaveplan/network-plugin-registry` package. All runtime failures within the registry layer are tagged with deterministic codes so callers can handle them programmatically. The registry is a critical component for mesh membership tracking, and clear error semantics are essential for reliable operation in distributed environments where peers may join, leave, or send malformed data at any time.
+
+## Features
+
+- Deterministic code generation via `defineCodes`
+- Typed error class extending `SuaveplanError`
+- Full OpenTelemetry span-event compatibility
+- Tree-shake safe code definitions
+- Machine-readable error categorization
+- Human-readable message keys for i18n
+
+## Usage
+
+### Basic Example
+
+```ts
+import { NetworkRegError, NETWORK_REG_CODES } from "@suaveplan/network-plugin-registry";
+
+throw new NetworkRegError(
+    NETWORK_REG_CODES.REGISTRY_FULL,
+    "registry.full"
+);
+```
+
+### Advanced Example
+
+```ts
+import { NetworkRegError, NETWORK_REG_CODES } from "@suaveplan/network-plugin-registry";
+
+try {
+    registry.add(peer);
+} catch (err) {
+    if (err instanceof NetworkRegError && err.code === NETWORK_REG_CODES.PEER_ALREADY_EXISTS) {
+        console.log("Peer already registered");
+    }
+}
+```
+
+## API Reference
+
+- `NETWORK_REG_CODES` — frozen registry of registry error codes
+- `NetworkRegError` — typed error class
+- `NetworkRegErrorCode` — union type of valid codes
+
+## Implementation Notes
+
+Codes are namespaced under `NET_REG` to avoid collisions with other network subsystems. The registry includes codes for capacity limits (`REGISTRY_FULL`), missing peers (`PEER_NOT_FOUND`), duplicate entries (`PEER_ALREADY_EXISTS`), and invalid peer data (`INVALID_PEER_DATA`). Each code maps to a human-readable message key that can be resolved for internationalization. The `NetworkRegError` class extends `SuaveplanError`, which provides automatic stack trace capture, cause chaining, and OpenTelemetry span event conversion. Error codes are tree-shake safe, meaning unused codes are removed from production bundles by the bundler. This keeps the final payload small even when many error codes are defined across the project.

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

@@ -0,0 +1,50 @@
+# RegistryPlugin
+
+## Purpose
+
+Integrates the registry system into a `NetworkNode`. `RegistryPlugin` implements `NetworkPlugin` and wires together the `Registry`, `BinaryMessageEncoder`, and `RegistrySyncManager` as a single cohesive unit. This plugin is the recommended way to add peer-registry capabilities to a node because it handles lifecycle ordering automatically.
+
+## Features
+
+- Implements `NetworkPlugin` for automatic lifecycle management
+- Exposes registry and encoder as public readonly properties
+- Automatic sync management via node lifecycle hooks
+- Configurable capacity at construction time
+- Clean shutdown via `dispose()`
+- Zero external dependencies beyond the network package
+
+## Usage
+
+### Basic Example
+
+```ts
+import { RegistryPlugin } from "@suaveplan/network-plugin-registry";
+
+const plugin = new RegistryPlugin(32);
+node.use(plugin);
+```
+
+### Advanced Example
+
+```ts
+import { RegistryPlugin } from "@suaveplan/network-plugin-registry";
+
+const plugin = new RegistryPlugin(16);
+node.use(plugin);
+plugin.registry.add(peer);
+const bytes = plugin.encoder.encode(peer);
+```
+
+## API Reference
+
+- `name: "registry"` — plugin identifier
+- `registry: Registry` — peer registry
+- `encoder: BinaryMessageEncoder` — binary encoder
+- `install(node)` — wire sync manager to bus
+- `start()` — begin periodic sync
+- `stop()` — stop periodic sync
+- `dispose()` — clear registry and release sync manager
+
+## Implementation Notes
+
+The plugin creates the registry and encoder eagerly in the constructor so they are immediately available for inspection or manual mutation before the node is started. The sync manager is created lazily during `install()` when the node (and its bus) becomes available. This separation allows tests to construct and exercise the registry without needing a full `NetworkNode`. Disposing the plugin clears all registry state and drops the sync manager reference, which is important for clean shutdown and test isolation. The plugin never restarts automatically after disposal; a new instance must be created if registry functionality is needed again.

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

@@ -0,0 +1,54 @@
+# Registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Maintains a fixed-capacity in-memory registry of mesh peers. The registry provides CRUD operations: add, remove, get, list, and capacity enforcement. It is the authoritative source of peer membership information within a single network node. By capping the number of tracked peers, the registry prevents unbounded memory growth in large or adversarial meshes.
+
+## Features
+
+- Fixed capacity with configurable limit (default 32)
+- O(1) add, remove, get, and has operations via native Map
+- List all peers as an immutable read-only array
+- Duplicate detection with clear, typed errors
+- Full registry clear for shutdown or reset scenarios
+- Size getter for quick capacity monitoring
+
+## Usage
+
+### Basic Example
+
+```ts
+import { Registry } from "@suaveplan/network-plugin-registry";
+
+const registry = new Registry(32);
+registry.add({ peerId: "p1", address: "192.168.1.1", tier: 1, latencyMs: 10 });
+```
+
+### Advanced Example
+
+```ts
+import { Registry } from "@suaveplan/network-plugin-registry";
+
+const registry = new Registry(16);
+registry.add(peer);
+console.log(registry.list());
+registry.remove("p1");
+```
+
+## API Reference
+
+- `constructor(capacity?)` — create registry with capacity limit
+- `add(entry): void` — add peer, throws if full or duplicate
+- `remove(peerId): boolean` — remove peer by ID
+- `get(peerId): PeerEntry | undefined` — lookup peer
+- `list(): PeerEntry[]` — list all peers
+- `has(peerId): boolean` — check membership
+- `size: number` — current peer count
+- `clear(): void` — remove all peers
+
+## Implementation Notes
+
+The registry uses a JavaScript `Map` for O(1) operations. Capacity is enforced strictly: adding a peer when at capacity throws `REGISTRY_FULL`. Duplicate peer IDs throw `PEER_ALREADY_EXISTS`. The `list()` method returns a shallow copy of the internal values to prevent external mutation of internal state. Removing a peer that does not exist returns `false` rather than throwing, making idempotent cleanup easy. The registry is not thread-safe in the traditional sense, but because JavaScript is single-threaded, concurrent mutation is impossible as long as async boundaries are respected.

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

@@ -0,0 +1,48 @@
+# RegistrySyncManager
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Periodically syncs registry state to the `NetworkBus` via `registry:update` events. This keeps other plugins informed of mesh membership changes without requiring them to poll the registry directly. The sync manager is the bridge between the local registry and the rest of the network stack.
+
+## Features
+
+- Configurable sync interval (default 5000ms)
+- Start/stop lifecycle matching node lifecycle
+- One-shot sync method for on-demand updates
+- Automatic timer cleanup on stop
+- Emits full peer list with timestamp
+
+## Usage
+
+### Basic Example
+
+```ts
+import { RegistrySyncManager } from "@suaveplan/network-plugin-registry";
+
+const sync = new RegistrySyncManager(registry, bus, 5000);
+sync.start();
+```
+
+### Advanced Example
+
+```ts
+import { RegistrySyncManager } from "@suaveplan/network-plugin-registry";
+
+const sync = new RegistrySyncManager(registry, bus);
+sync.sync();
+sync.stop();
+```
+
+## API Reference
+
+- `constructor(registry, bus, intervalMs?)` — create sync manager
+- `start(): void` — begin periodic sync
+- `stop(): void` — stop periodic sync
+- `sync(): void` — emit single update event
+
+## Implementation Notes
+
+The sync interval defaults to 5000ms, which is a balance between timeliness and event bus load. The `registry:update` event payload includes the full peer list and a timestamp. Callers should filter or debounce if processing these events is expensive. The manager does not diff changes — it always emits the complete state. This simplifies implementation and guarantees that subscribers always have an accurate snapshot, at the cost of slightly larger event payloads. Stopping the manager clears the internal timer and sets the reference to `undefined`, preventing memory leaks during long-running application shutdown.