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.