Updates

scheduling-queues/hyper-p2p-deadline-queue/README.md

@@ -1,28 +1,35 @@
 # hyper-p2p-deadline-queue
 
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `deadline-queue/v1` · **Wave:** 8
+Priority queue ordered by deadline with `drain(now)` for due tasks.
 
-Deadline-priority queue.
+**Category:** scheduling-queues
 
-## Holepunch references (inspiration only)
+**Protocol:** `deadline-queue/v1`
 
-- `hyper-p2p-activity-queue`
+## When to use
 
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+Scheduling work items that must run before a timestamp (ms).
 
-## Composes with
+## When not to use
 
-- `hyper-p2p-peer-scheduler`
+Recurring cron-style jobs (use hyper-p2p-cron-gossip).
 
-## Planned API
+## Quick start
 
-- `constructor(opts)` — topic, optional keyPair
-- `getStats()` — scaffold counters
-- `ready()` — no-op until implemented
-- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
+```js
+const { HyperP2PDeadlineQueue } = require('hyper-p2p-deadline-queue')
+const q = new HyperP2PDeadlineQueue()
+q.enqueue('t1', { run: true }, Date.now() + 1000)
+console.log(q.drain(Date.now() + 2000))
+```
 
-## Layout
+## Docs
 
-`modules/scheduling-queues/hyper-p2p-deadline-queue/`
+- [docs/api.md](docs/api.md)
+- [docs/architecture.md](docs/architecture.md)
 
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+## Test
+
+```bash
+npm install && npm test
+```

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

@@ -1,23 +1,11 @@
-# hyper-p2p-deadline-queue API
+# API: hyper-p2p-deadline-queue
 
-**Status:** scaffold · **Protocol:** `deadline-queue/v1`
+**Export:** `HyperP2PDeadlineQueue`
 
-## Class `HyperP2PDeadlineQueue`
+## Methods
 
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+### `enqueue(id, task, deadline)` / `drain(now)` / `peek()`
 
-### `constructor(opts?)`
+`drain` returns all entries with `deadline <= now`.
 
-### `getStats()`
-
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
-
-### `ready()`
-
-Resolves immediately (no-op).
-
-## Wire (planned)
-
-| Message | Direction | Notes |
-|---------|-----------|-------|
-| TBD | gossip | Defined in implementation pass |
+### `cancel(id)` / `get(id)` / `pending()` / `list()` / `getStats()` / `close()`

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

@@ -1,15 +1,5 @@
-# hyper-p2p-deadline-queue architecture
+# Architecture: hyper-p2p-deadline-queue
 
-**Tier:** scaffold · **Category:** `scheduling-queues`
+**Category:** scheduling-queues
 
-## Role
-
-Deadline-priority queue.
-
-## Composition
-
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
-
-## Holepunch boundary
-
-Inspiration: n/a
+Sorted array by deadline plus `_byId` index for cancel/replace. `peek` returns earliest entry without removal.

scheduling-queues/hyper-p2p-deadline-queue/examples/basic.js

@@ -2,7 +2,11 @@ require('bare-process/global')
 const { HyperP2PDeadlineQueue } = require('../index.js')
 
 async function main () {
-  const m = new HyperP2PDeadlineQueue()
-  console.log('[scaffold]', m.getStats())
+  const q = new HyperP2PDeadlineQueue()
+  const now = Date.now()
+  q.enqueue('job', { msg: 'hi' }, now + 500)
+  console.log('[deadline-queue]', q.peek(), q.drain(now + 600))
+  await q.close()
 }
+
 main().catch(console.error)

scheduling-queues/hyper-p2p-deadline-queue/index.js

@@ -1,7 +1,6 @@
 require('bare-process/global')
 const EventEmitter = require('bare-events')
 const { assertNonEmpty } = require('../../_shared/lib/errors.js')
-const { attachGossip, sendGossip } = require('../../_shared/storage-gossip-base.js')
 
 const PROTOCOL = 'deadline-queue/v1'
 
@@ -9,30 +8,87 @@ class HyperP2PDeadlineQueue extends EventEmitter {
   constructor (opts = {}) {
     super()
     this._queue = []
-    this._stats = { enqueued: 0, dequeued: 0 }
+    this._byId = new Map()
+    this._stats = { enqueued: 0, drained: 0 }
   }
 
-  enqueue (item, opts = {}) {
-    if (item == null) throw new Error('item required')
-    const entry = { item, deadline: opts.deadline || null, at: Date.now() }
+  enqueue (id, task, deadline) {
+    assertNonEmpty(id, 'id')
+    if (task == null) throw new Error('task required')
+    const dl = Number(deadline)
+    if (!Number.isFinite(dl)) throw new Error('deadline must be a number (ms timestamp)')
+    if (this._byId.has(id)) this.cancel(id)
+    const entry = { id, task, deadline: dl, at: Date.now() }
     this._queue.push(entry)
-    this._queue.sort((a, b) => (a.deadline || Infinity) - (b.deadline || Infinity))
+    this._queue.sort((a, b) => a.deadline - b.deadline)
+    this._byId.set(id, entry)
     this._stats.enqueued++
+    this.emit('enqueue', entry)
     return entry
   }
 
-  dequeue () {
-    const e = this._queue.shift() || null
-    if (e) this._stats.dequeued++
-    return e
+  peek () {
+    return this._queue[0] ? { ...this._queue[0] } : null
   }
 
-  peek () { return this._queue[0] || null }
+  drain (now = Date.now()) {
+    const ts = Number(now)
+    const due = []
+    const keep = []
+    for (const entry of this._queue) {
+      if (entry.deadline <= ts) {
+        due.push(entry)
+        this._byId.delete(entry.id)
+      } else {
+        keep.push(entry)
+      }
+    }
+    this._queue = keep
+    if (due.length) {
+      this._stats.drained += due.length
+      this.emit('drain', { now: ts, items: due.map((e) => e.id) })
+    }
+    return due
+  }
 
-  getStats () { return { ...this._stats, pending: this._queue.length, protocol: PROTOCOL } }
+  cancel (id) {
+    assertNonEmpty(id, 'id')
+    const had = this._byId.has(id)
+    if (!had) return false
+    this._queue = this._queue.filter((e) => e.id !== id)
+    this._byId.delete(id)
+    this.emit('cancel', { id })
+    return true
+  }
+
+  get (id) {
+    const e = this._byId.get(id)
+    return e ? { ...e } : null
+  }
+
+  pending () {
+    return this._queue.length
+  }
+
+  list () {
+    return this._queue.map((e) => ({ id: e.id, deadline: e.deadline }))
+  }
+
+  getStats () {
+    return {
+      ...this._stats,
+      pending: this._queue.length,
+      protocol: PROTOCOL
+    }
+  }
 
   async ready () { return this }
-  async close () { this._queue = [] }
+
+  async close () {
+    this._queue = []
+    this._byId.clear()
+    this.emit('closed')
+  }
 }
 
 module.exports = { HyperP2PDeadlineQueue, PROTOCOL }

scheduling-queues/hyper-p2p-deadline-queue/test/test.js

@@ -4,23 +4,38 @@ const { HyperP2PDeadlineQueue, PROTOCOL } = require('../index.js')
 
 test('exports', (t) => {
   t.ok(HyperP2PDeadlineQueue)
-  t.ok(PROTOCOL)
+  t.is(PROTOCOL, 'deadline-queue/v1')
 })
 
-test('basic operation', async (t) => {
+test('enqueue drain peek', async (t) => {
   const m = new HyperP2PDeadlineQueue()
-  m.enqueue({x:1}); t.ok(m.dequeue())
+  m.enqueue('a', { n: 1 }, 100)
+  m.enqueue('b', { n: 2 }, 50)
+  t.is(m.peek().id, 'b')
+  const due = m.drain(60)
+  t.is(due.length, 1)
+  t.is(due[0].id, 'b')
   await m.close()
 })
 
 test('validation', async (t) => {
   const m = new HyperP2PDeadlineQueue()
-  try { m.put(null, 1) } catch (e) { t.ok(e) }
+  try { m.enqueue('', null, 1) } catch (e) { t.ok(e) }
+  await m.close()
+})
+
+test('cancel', async (t) => {
+  const m = new HyperP2PDeadlineQueue()
+  m.enqueue('z', {}, 999)
+  t.ok(m.cancel('z'))
+  t.is(m.pending(), 0)
   await m.close()
 })
 
 test('getStats', async (t) => {
   const m = new HyperP2PDeadlineQueue()
-  t.ok(m.getStats().protocol)
+  m.enqueue('j', {}, 1)
+  t.is(m.getStats().protocol, 'deadline-queue/v1')
+  t.is(m.getStats().enqueued, 1)
   await m.close()
 })