Update Docs

hyper-p2p-anycast-selector/docs/api.md

@@ -4,6 +4,10 @@
 
 **Export:** `HyperP2PAnycastSelector`
 
+## Overview
+
+Production network stack module: Hyperswarm discovery + Protomux when `topic` is set.
+
 ## Constructor
 
 ```js
@@ -12,31 +16,60 @@ const mod = new HyperP2PAnycastSelector(opts)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `topic` | `string` \| `Buffer` | `null` | Hyperswarm topic |
-| `keyPair` | `KeyPair` | random | Ed25519 key pair |
-| `enableBackgroundTimers` | `boolean` | `false` | Background timers (off in tests) |
+| `topic` | varies | null | topic |
+| `keyPair` | KeyPair | random Ed25519 | keyPair |
 
 ## Methods
 
-| Method | Returns | Throws |
-|--------|---------|--------|
-| `getStats()` | `object` | — |
-| `close()` | `Promise<void>` | — |
-| `ready(...)` | `Promise` or value | May throw `Error` on invalid input |
-| `registerCapability(...)` | `Promise` or value | May throw `Error` on invalid input |
-| `resolve(...)` | `Promise` or value | May throw `Error` on invalid input |
-| `updateLatency(...)` | `Promise` or value | May throw `Error` on invalid input |
+### `registerCapability(tag, peerId = null)`
+
+- **Returns:** `value`
+- **Throws:**
+  - `Error: tag required`
+
+### `updateLatency(peerId, ms)`
+
+- **Returns:** `value`
+- **Throws:**
+  - `Error: latency must be non-negative`
+  - `Error: peerId required`
+
+### `resolve(tag)`
+
+- **Returns:** `value`
+- **Throws:**
+  - `Error: tag required`
+
+### `getStats(—)`
+
+- **Returns:** `object`
+- **Throws:** — (none documented in method body)
+
+### `ready(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `close(—)`
+
+- **Returns:** `Promise<void>`
+- **Throws:** — (none documented in method body)
 
 ## Events
 
-| Event | Description |
-|-------|-------------|
-| `closed` | Emitted on state change |
-| `resolved` | Emitted on state change |
+| Event | Payload |
+|-------|---------|
+| `closed` | no payload |
+| `resolved` | peerId, rttMs |
 
-## Metrics
+## getStats()
 
-`getStats()` returns operation counters (`ops`, `errors`, etc.) or `mode: 'local'` for library-only modules.
+Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
+Library-only modules may include `mode: 'local'`.
+
+## Errors
+
+Stable message substrings: see [`../_shared/ERROR_CODES.md`](../_shared/ERROR_CODES.md).
 
 ## P2P
 
@@ -48,4 +81,4 @@ When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `anycast-sele
 npm install && npm test
 ```
 
-Integration: [`../../real_tests/integration/anycast-selector-two-node.js`](../../real_tests/integration/anycast-selector-two-node.js)
+Integration: [`../../real_tests/integration/anycast-selector-two-node.js`](../../real_tests/integration/anycast-selector-two-node.js)

hyper-p2p-anycast-selector/docs/architecture.md

@@ -9,19 +9,38 @@ flowchart LR
   Mux --> Swarm[Hyperswarm]
 ```
 
+## Sequence (P2P)
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Mod as Module
+  participant SW as Hyperswarm
+  participant Peer
+  App->>Mod: ready(topic)
+  Mod->>SW: join(topic)
+  SW->>Peer: connection
+  Mod->>Peer: gossip / Protomux
+  Peer-->>Mod: onmessage
+  Mod-->>App: emit(event)
+```
+
 ## Wire messages
 
-| type | payload | direction |
-|------|---------|-----------|
-| `cap-register` | JSON payload | gossip |
-| `latency` | JSON payload | gossip |
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| `cap-register` | ms, peerId, tag | gossip | Handled in onmessage / gossipSend |
+| `latency` | ms, peerId | gossip | Handled in onmessage / gossipSend |
+
+## State model
+
+- In-memory `Map` / `Set` structures for hot path
+- Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
+- `close()` tears down swarm, timers, and clears ephemeral state
 
 ## Composition
 
 Composes with: `hyper-p2p-protocol-handshake`, `hyper-p2p-connection-pool`, `hyper-p2p-overlay-topology`.
 
-See [`../_shared/WAVE6_NETWORK_STACK.md`](../_shared/WAVE6_NETWORK_STACK.md) when using network-stack modules.
+See [`../_shared/WAVE6_NETWORK_STACK.md`](../_shared/WAVE6_NETWORK_STACK.md) for layer ordering.
 
-## State
-
-In-memory structures; gossip merges remote updates when `topic` is configured.