Updates

scheduling-queues/hyper-p2p-deadline-queue/docs/api.md

@@ -1,11 +1,106 @@
 # API: hyper-p2p-deadline-queue
 
-**Export:** `HyperP2PDeadlineQueue`
+**Protocol:** `deadline-queue/v1` (metadata constant; no network transport)
+
+**Export:** `{ HyperP2PDeadlineQueue, PROTOCOL }`
+
+## Overview
+
+`HyperP2PDeadlineQueue` is a local `EventEmitter` priority queue ordered by `deadline` ms timestamp. `enqueue` replaces duplicate ids. `drain(now)` extracts all entries with `deadline <= now`. No P2P: `ready()` resolves immediately; use alongside cron or consensus modules for distributed triggers.
+
+## Constructor
+
+```js
+const q = new HyperP2PDeadlineQueue()
+```
+
+No options.
 
 ## Methods
 
-### `enqueue(id, task, deadline)` / `drain(now)` / `peek()`
+### `enqueue(id, task, deadline)`
 
-`drain` returns all entries with `deadline <= now`.
+- **Parameters:**
+  - `id` — unique string id
+  - `task` — arbitrary payload (must not be null)
+  - `deadline` — finite ms timestamp
+- **Returns:** entry `{ id, task, deadline, at }`
+- **Throws:**
+  - `ValidationError: id is required`
+  - `Error: task required`
+  - `Error: deadline must be a number (ms timestamp)`
+- **Emits:** `enqueue`
 
-### `cancel(id)` / `get(id)` / `pending()` / `list()` / `getStats()` / `close()`
+### `peek()`
+
+- **Returns:** shallow copy of earliest entry or `null`
+
+### `drain(now = Date.now())`
+
+- **Returns:** `entry[]` due items (full objects)
+- **Emits:** `drain` with `{ now, items: id[] }` when non-empty
+
+### `cancel(id)`
+
+- **Returns:** `boolean`
+- **Emits:** `cancel`
+
+### `get(id)` / `pending()` / `list()`
+
+Query helpers; `list()` returns `{ id, deadline }` only.
+
+### `async ready()`
+
+No-op resolve for API symmetry.
+
+### `async close()`
+
+Clears queue, emits `closed`.
+
+### `getStats()`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enqueued` | `number` | Successful enqueues |
+| `drained` | `number` | Entries removed by `drain` |
+| `pending` | `number` | Queue length |
+| `protocol` | `string` | `deadline-queue/v1` |
+
+## Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `enqueue` | entry | New/replaced task |
+| `drain` | `{ now, items }` | One or more tasks due |
+| `cancel` | `{ id }` | Removed by id |
+| `closed` | — | `close()` |
+
+## getStats()
+
+Shallow copy; `pending` is live length.
+
+## Wire
+
+No wire messages. `PROTOCOL` is exported for module registry consistency only.
+
+## Errors
+
+| Message | Source |
+|---------|--------|
+| `id is required` | `enqueue` / `cancel` |
+| `task required` | `enqueue` |
+| `deadline must be a number (ms timestamp)` | invalid deadline |
+
+## Testing
+
+```bash
+cd modules/scheduling-queues/hyper-p2p-deadline-queue
+npm install && npm test
+bare examples/basic.js
+```
+
+Pass explicit `now` to `drain` for deterministic ordering tests.
+
+## Composition
+
+Run a timer loop: `setInterval(() => { const due = q.drain(); due.forEach(runTask) }, 100)` after enqueuing work from `hyper-p2p-cron-gossip` `fire` handlers.

scheduling-queues/hyper-p2p-deadline-queue/docs/architecture.md

@@ -1,5 +1,27 @@
 # Architecture: hyper-p2p-deadline-queue
 
-**Category:** scheduling-queues
+**Protocol:** `deadline-queue/v1` (local only)
 
-Sorted array by deadline plus `_byId` index for cancel/replace. `peek` returns earliest entry without removal.
+```mermaid
+flowchart LR
+  App --> DQ[HyperP2PDeadlineQueue]
+  DQ --> Q["_queue sorted by deadline"]
+  DQ --> Map["_byId Map"]
+```
+
+## Wire messages
+
+| type | fields | direction | behavior |
+|------|--------|-----------|----------|
+| — | — | — | No network layer |
+
+## State model
+
+| Structure | Role |
+|-----------|------|
+| `_queue` | Array sorted ascending by `deadline` |
+| `_byId` | Fast lookup / cancel |
+
+## Composition
+
+Downstream executor for `hyper-p2p-cron-gossip` and `hyper-p2p-task-orchestrator`; not a distributed queue by itself.