Updates

trust-security/hyper-p2p-reputation-system/docs/api.md

@@ -0,0 +1,124 @@
+# API: hyper-p2p-reputation-system
+
+**Protocol:** `hyper-p2p-reputation-system/v1`
+
+**Export:** `HyperP2PReputationSystem`
+
+## Overview
+
+HyperP2PReputationSystem Novel P2P reputation/trust primitive for Bare/Pear. - Cryptographic Ed25519 signed attestations for tamper-proof updates - Time-decaying scores with configurable rate
+
+## Constructor
+
+```js
+const mod = new HyperP2PReputationSystem(opts)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `keyPair` | KeyPair | random Ed25519 | keyPair |
+| `storageDir` | `<cwd>/{module}-storage` | `<cwd>/{module}-storage` | Hypercore/Hyperbee storage root |
+| `decayIntervalMs` | varies | DEFAULT_DECAY_INTERVAL_MS | decayInterval (ms) |
+| `decayRate` | varies | DEFAULT_DECAY_RATE | decayRate |
+| `minScore` | varies | DEFAULT_MIN_SCORE | minScore |
+| `maxScore` | varies | DEFAULT_MAX_SCORE | maxScore |
+| `topic` | varies | null | topic |
+| `enableBackgroundTimers` | boolean | `false` | Periodic timers (off in tests) |
+
+## Methods
+
+### `ready(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `attest(targetPeerId, delta, metadata = {}, remoteAttestation = null)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `receiveAttestation(attestation, targetPeerId)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `getReputation(peerId)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `getTopPeers(k = 10)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `getHistory(peerId, limit = 50)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `exportSnapshot(—)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `importSnapshot(snapshot)`
+
+- **Returns:** `Promise`
+- **Throws:**
+  - `Error: Invalid or unsupported snapshot version`
+  - `Error: Invalid snapshot: must be an object`
+
+### `getStats(—)`
+
+- **Returns:** `object`
+- **Throws:** — (none documented in method body)
+
+### `close(—)`
+
+- **Returns:** `Promise<void>`
+- **Throws:** — (none documented in method body)
+
+### `getCausalTick(—)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `simulateRemoteAttestation(targetPeerId, delta, fromPeerHex = 'remote-peer')`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `attestation` | target, local |
+| `close` | no payload |
+| `error` | err |
+| `hyperbee-fallback` | err |
+| `peerBanned` | score |
+| `ready` | no payload |
+| `scoreUpdated` | peerId, score, attester |
+| `snapshotImported` | timestamp, scoresCount, historyEntries |
+
+## 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 `hyper-p2p-reputation-system/v1`.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Integration: [`../../real_tests/integration/reputation-system-two-node.js`](../../../real_tests/integration/reputation-system-two-node.js)

trust-security/hyper-p2p-reputation-system/docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture: hyper-p2p-reputation-system
+
+**Category:** Trust & security
+
+```mermaid
+flowchart LR
+  App[Application] --> Mod[HyperP2PReputationSystem]
+  Mod --> Mux[Protomux hyper-p2p-reputation-system/v1]
+  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 | fields | direction | behavior |
+|------|--------|-----------|----------|
+| `attestation` | attestation, target | 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-attestation-chain`, `hyper-p2p-trust-graph`.
+