Updates

encoding-wire/hyper-p2p-wire-registry/docs/api.md

@@ -1,100 +1,81 @@
 # API: hyper-p2p-wire-registry
 
-**Protocol:** `wire-registry/v1`
+**Protocol:** `wire-registry/v1` (local registry)
 
-**Export:** `HyperP2PWireRegistry`
+**Export:** `HyperP2PWireRegistry`, `PROTOCOL`
 
 ## Overview
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Central registry of `compact-encoding` codecs and protocol id metadata for consistent encode/decode across modules.
 
 ## Constructor
 
-```js
-const mod = new HyperP2PWireRegistry(opts)
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
-| `keyPair` | KeyPair | random | Ed25519 key pair |
+| Option | Description |
+|--------|-------------|
+| `types` | Optional `Map(id, codec)` seed entries |
 
 ## Methods
 
-### `registerCodec(id, codec)`
+### `registerCodec(id, codec)` / `encode(id, value)` / `decode(id, buf)`
 
-- **Returns:** `value`
-- **Throws:**
-  - `Error: codec required`
+- **Throws:** `unknown codec id`
 
-### `registerProtocol(protocolId, meta = {})`
+### `registerProtocol(protocolId, meta?)` / `hasProtocol` / `listProtocols()`
 
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
+Emits `protocol` on register.
 
-### `hasProtocol(protocolId)`
+### `getStats()` / `ready()` / `close()`
 
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
+`codecs`, `protocols` counts.
 
-### `encode(id, value)`
+## Wire
 
-- **Returns:** `value`
-- **Throws:**
-  - `Error: unknown codec id`
+Registry does not send frames; stores protocol strings like `topic-channel/v1` for tooling.
 
-### `decode(id, buf)`
+## Composition
 
-- **Returns:** `value`
-- **Throws:**
-  - `Error: unknown codec id`
-
-### `listProtocols(—)`
-
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
-
-### `negotiate(offered = [])`
-
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
-
-### `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 | Payload |
-|-------|---------|
-| `protocol` | payload object |
-
-## getStats()
-
-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
-
-When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `wire-registry/v1`.
+`hyper-p2p-message-envelope`, `hyper-p2p-compact-codec-bridge`, `hyper-p2p-schema-validator`.
 
 ## Testing
 
-```bash
-npm install && npm test
-```
+`npm test`
+
+## Example
+
+`examples/basic.js`
+
+## State model
+
+Separate maps for codecs and protocol metadata; `listProtocols` returns keys only.
+
+## Performance
+
+Encode/decode delegates to compact-encoding — register codecs once at boot.
+
+## Versioning
+
+Protocol registration is append-only in typical deployments.
+
+## Security
+
+Unknown codec ids throw on encode — validate ids from trusted configuration only.
+
+## Related modules
+
+- `hyper-p2p-schema-validator` — payload validation
+
+## Changelog
+
+- Wave 9: protocol + codec registry for cross-module wire consistency.
+- `registerProtocol` emits `protocol` event for dynamic UIs.
+
+## Integration checklist
+
+1. Register codecs at app boot from shared map.
+2. `registerProtocol('topic-channel/v1', { module: '...' })`.
+3. Use `encode`/`decode` in RPC bridges only with known ids.
+4. `listProtocols()` for admin/debug panels.
+
+## See also
+
+[`docs/architecture.md`](architecture.md)