Updates

scheduling-queues/hyper-p2p-peer-scheduler/docs/api.md

@@ -0,0 +1,80 @@
+# API: hyper-p2p-peer-scheduler
+
+**Protocol:** `peer-scheduler/v1`
+
+**Export:** `HyperP2PPeerScheduler`
+
+## Overview
+
+Library-only scheduling & queues primitive for Bare/Pear (no mandatory Hyperswarm topic).
+
+## Constructor
+
+```js
+const mod = new HyperP2PPeerScheduler(opts)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | varies | null | topic |
+| `keyPair` | KeyPair | random Ed25519 | keyPair |
+| `topicLease` | varies | null | topicLease |
+| `leaderShard` | varies | opts.topic || 'default-shard' | leaderShard |
+| `enableBackgroundTimers` | boolean | `false` | Periodic timers (off in tests) |
+
+## Methods
+
+### `schedule(expr, jobId, opts = {})`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `cancel(jobId)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `ready(—)`
+
+- **Returns:** `Promise`
+- **Throws:** — (none documented in method body)
+
+### `getStats(—)`
+
+- **Returns:** `object`
+- **Throws:** — (none documented in method body)
+
+### `close(—)`
+
+- **Returns:** `Promise<void>`
+- **Throws:** — (none documented in method body)
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `cancelled` | payload object |
+| `closed` | no payload |
+| `scheduled` | payload object |
+| `tick` | jobId, expr, shard |
+
+## 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
+
+No Hyperswarm topic required; use Protomux attach helpers where documented.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Integration: [`../../real_tests/integration/peer-scheduler-two-node.js`](../../../real_tests/integration/peer-scheduler-two-node.js)

scheduling-queues/hyper-p2p-peer-scheduler/docs/architecture.md

@@ -0,0 +1,27 @@
+# Architecture: hyper-p2p-peer-scheduler
+
+**Category:** Scheduling & queues
+
+```mermaid
+flowchart LR
+  App[Application] --> Mod[HyperP2PPeerScheduler]
+  Mod --> Mux[Protomux peer-scheduler/v1]
+  Mux --> Swarm[Hyperswarm]
+```
+
+## Wire messages
+
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| *(local only)* | — | — | No gossip wire types |
+
+## 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-activity-queue`, `hyper-p2p-topic-lease`.
+