first commit

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.