Updates

trust-security/hyper-p2p-multisig-threshold/docs/api.md

@@ -1,26 +1,85 @@
 # API: hyper-p2p-multisig-threshold
 
-**Protocol:** `multisig-threshold/v1` · **Export:** `HyperP2PMultisigThreshold`
+**Protocol:** `multisig-threshold/v1` · **Export:** `HyperP2PMultisigThreshold`, `PROTOCOL`
+
+## Overview
+
+Threshold signature coordination for proposals: create with signer list and threshold, collect signatures until `threshold` met, gossip create and sig messages.
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
+| `keyPair` | `KeyPair` | random | Identity |
 
 ## Methods
 
-### `createProposal(...)`
+### `createProposal(id, signers, threshold)`
 
-Domain API.
+- **Returns:** `{ id, signers, threshold }`
+- **Throws:** `signers must be a non-empty array`; `threshold must be between 1 and signers.length`
+- **Gossip:** `{ type: 'proposal-create', id, signers, threshold, createdAt }`
+- **Emits:** `proposal`
 
-### `addSignature(...)`
+### `addSignature(id, signer)`
 
-Domain API.
+- **Returns:** `{ id, signer, count, approved }`
+- **Throws:** `proposal not found: ${id}`; `signer not authorized: ${signer}`
+- **Gossip:** `{ type: 'proposal-sig', id, signer }`
+- **Emits:** `approved` when threshold first reached
 
-### `isApproved(...)`
+### `isApproved(id)`
 
-Domain API.
+- **Returns:** boolean
 
+### `ready()` / `close()`
 
-### `getStats()` / `ready()` / `close()`
+Standard.
 
-Lifecycle helpers.
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `proposal` | `{ id, signers, threshold }` |
+| `approved` | `{ id }` |
+| `closed` | — |
+
+## getStats()
+
+`created`, `signatures`, `approved`, `gossipIn`, `gossipOut`, `proposals`, `protocol`.
+
+## Wire
+
+| type | fields | behavior |
+|------|--------|----------|
+| `proposal-create` | `id`, `signers`, `threshold`, `createdAt` | Insert proposal if missing |
+| `proposal-sig` | `id`, `signer` | Add sig if signer authorized; maybe approve |
+
+## Errors
+
+Validation strings above; `assertNonEmpty` on ids.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 
 ## P2P
 
-Joins Hyperswarm when `topic` is set.
+Signatures stored in `Set` per proposal (not deduplicated across duplicate gossip).
+
+## Testing
+
+```bash
+cd modules/trust-security/hyper-p2p-multisig-threshold && npm test
+```
+
+## Composition
+
+`hyper-p2p-key-rotation`, agent workflows requiring quorum.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## See also
+
+[`docs/architecture.md`](architecture.md).

trust-security/hyper-p2p-multisig-threshold/docs/architecture.md

@@ -1,12 +1,18 @@
 # Architecture: hyper-p2p-multisig-threshold
 
+**Protocol:** `multisig-threshold/v1` · **Category:** trust-security
+
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| `proposal-create` | id, signers, threshold | gossip | Create |
-| `proposal-sig` | id, signer | gossip | Sign |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `proposal-create` | gossip | `id`, `signers`, `threshold`, `createdAt` | Create `_proposals` entry |
+| `proposal-sig` | gossip | `id`, `signer` | Add to `signatures` Set; set `approved` at threshold |
 
-## State
+## State model
 
-In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
+`_proposals`: Map id → `{ id, signers, threshold, signatures: Set, createdAt, approved }`.
+
+## Composition
+
+`hyper-p2p-key-rotation`, `hyper-p2p-workflow-graph`.