Updates

consensus-coordination/hyper-p2p-raft-lite/docs/api.md

@@ -1,13 +1,91 @@
 # API: hyper-p2p-raft-lite
 
-**Export:** `HyperP2PRaftLite` · **Protocol:** `raft-lite/v1`
+**Protocol:** `raft-lite/v1`
+
+**Export:** `{ HyperP2PRaftLite, PROTOCOL }`
+
+## Overview
+
+`HyperP2PRaftLite` is a teaching-weight Raft subset: local `_log` array of `{ term, entry, index }`, `_commitIndex`, and `_role` (`leader` | `follower`). `appendLog` pushes locally and gossips `raft-lite-append`. `becomeLeader(term)` promotes self and gossips `raft-lite-role`. Inbound gossip extends the log and advances commit index when indices grow.
+
+This is **not** a complete Raft implementation—no elections, snapshots, or safety proofs.
+
+## Constructor
+
+```js
+const raft = new HyperP2PRaftLite(opts)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` \| `Buffer` \| `null` | `null` | Hyperswarm topic |
+| `keyPair` | `KeyPair` | `hypercore-crypto.keyPair()` | Swarm identity |
+| `peerId` | `string` | hex public key | Sender id on role messages |
+| `role` | `string` | `'follower'` | Initial role |
 
 ## Methods
 
-- `appendLog(entry)` — append local log record, gossip append
-- `commitIndex()` — highest known committed index
-- `role()` — `follower` | `leader` (via `becomeLeader`)
-- `becomeLeader(term)` — promote and gossip role
-- `getStats()` / `ready()` / `close()`
+### `appendLog(entry)`
 
-Wire: `raft-lite-append`, `raft-lite-role`.
+Appends at `index = _log.length` with `term = _currentTerm`.
+
+- **Returns:** `number` — log index
+- **Gossip:** `raft-lite-append` with `{ term, entry, index }`
+
+### `commitIndex()`
+
+- **Returns:** `number` — highest known committed index (`-1` when empty)
+
+### `role()`
+
+- **Returns:** `string` — `_role`
+
+### `becomeLeader(term)`
+
+When `term >= _currentTerm`, sets role `leader` and gossips role message.
+
+- **Returns:** `void`
+
+### `async ready()` / `async close()`
+
+Gossip swarm lifecycle.
+
+### `getStats()`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `appends` | `number` | Local append count |
+| `gossipIn` / `gossipOut` | `number` | Wire counters |
+| `role` | `string` | Current role |
+| `logLength` | `number` | `_log.length` |
+| `commitIndex` | `number` | `_commitIndex` |
+| `protocol` | `string` | `raft-lite/v1` |
+
+## Events
+
+None emitted.
+
+## getStats()
+
+Shallow copy including `role` and `commitIndex`.
+
+## Wire
+
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| `raft-lite-append` | `term`, `entry`, `index` | bidirectional | Push if `index >= log.length`; bump `_commitIndex` |
+| `raft-lite-role` | `peer`, `role`, `term` | bidirectional | Update term and `_role` when `term >= _currentTerm` |
+
+## Errors
+
+No module-specific throws beyond shared `topic is required for createSwarm`.
+
+## Testing
+
+```bash
+cd modules/consensus-coordination/hyper-p2p-raft-lite
+npm install && npm test
+bare examples/basic.js
+```
+
+Integration: two peers, shared topic, leader appends, follower log length catches up via gossip.

consensus-coordination/hyper-p2p-raft-lite/docs/architecture.md

@@ -1,5 +1,31 @@
 # Architecture: hyper-p2p-raft-lite
 
-In-memory log array with `{ term, entry, index }`. Followers learn appends and advance `commitIndex` on gossip. Role changes are advisory (no quorum math). Pair with `hyper-p2p-leader-lease` for soft leader hints.
+**Protocol:** `raft-lite/v1`
 
-Not durable; restart clears state.
+```mermaid
+flowchart TB
+  App --> RL[HyperP2PRaftLite]
+  RL --> Log["_log array"]
+  RL --> Role["_role, _currentTerm"]
+  RL --> Append[raft-lite-append]
+  RL --> RoleMsg[raft-lite-role]
+```
+
+## Wire messages
+
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| `raft-lite-append` | `term`, `entry`, `index` | bidirectional | Grow log; update commit index |
+| `raft-lite-role` | `peer`, `role`, `term` | bidirectional | Follow leader term/role hints |
+
+## State model
+
+| Field | Role |
+|-------|------|
+| `_log` | Ordered records |
+| `_commitIndex` | Highest index seen |
+| `_role` | Local process role string |
+
+## Composition
+
+Stack under `hyper-p2p-task-orchestrator` for ordered job dispatch; use `hyper-p2p-leader-lease` to decide who may call `becomeLeader`.