Updates

scheduling-queues/hyper-p2p-topic-lease/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+*-storage/

scheduling-queues/hyper-p2p-topic-lease/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.0] - 2026-05-20
+
+### Added
+- Initial v0.1.0 scaffold with Bare-compatible API, brittle tests, and docs.
+<!-- legacy: v0.2.0 -->
+
+- Production-grade docs, validation, and expanded tests.
+<!-- legacy: v0.3.0 -->
+
+- Wave 6: presence-tier API tables, architecture wire section, validation test.
+
+<!-- legacy: v0.3.1 -->
+
+- Wave 7: correct protocol in docs, getStats(), wire tables, category README.
+## [0.3.2] - 2026-05-21
+
+### Changed
+- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.

scheduling-queues/hyper-p2p-topic-lease/README.md

@@ -0,0 +1,43 @@
+# hyper-p2p-topic-lease
+
+Production scheduling & queues module: Hyperswarm discovery + Protomux when `topic` is set.
+
+**Category:** Scheduling & queues
+
+**Composes with:** `hyper-p2p-activity-queue`, `hyper-p2p-peer-scheduler`
+
+**Protocol:** `topic-lease/v1`
+
+## When to use
+
+Multi-peer apps that need scheduling & queues over a shared Hyperswarm topic.
+
+## When not to use
+
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
+
+## Quick start
+
+```js
+const { HyperP2PTopicLease } = require('hyper-p2p-topic-lease')
+const topic = process.argv[2] // 64-char hex or string
+const mod = new HyperP2PTopicLease({ topic, enableBackgroundTimers: false })
+await mod.ready()   // joins swarm when topic set
+// ... application logic ...
+await mod.close()
+```
+
+## Docs
+
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
+- [docs/architecture.md](docs/architecture.md) — wire types, state, composition
+- [../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
+- [../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
+
+- Integration: [`../../real_tests/integration/`](../../../real_tests/integration/) — `topic-lease-two-node.js`
+
+## Test
+
+```bash
+npm install && npm test
+```

scheduling-queues/hyper-p2p-topic-lease/docs/api.md

@@ -0,0 +1,95 @@
+# API: hyper-p2p-topic-lease
+
+**Protocol:** `topic-lease/v1`
+
+**Export:** `HyperP2PTopicLease`
+
+## Overview
+
+Production scheduling & queues module: Hyperswarm discovery + Protomux when `topic` is set.
+
+## Constructor
+
+```js
+const mod = new HyperP2PTopicLease(opts)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | varies | null | topic |
+| `keyPair` | KeyPair | random Ed25519 | keyPair |
+| `leaseMs` | varies | DEFAULT_LEASE_MS | lease (ms) |
+| `enableBackgroundTimers` | boolean | `false` | Periodic timers (off in tests) |
+
+## Methods
+
+### `acquire(topicShard)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `renew(topicShard)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `release(topicShard)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `holder(topicShard)`
+
+- **Returns:** `value`
+- **Throws:** — (none documented in method body)
+
+### `holderOf(topicShard)`
+
+- **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 |
+|-------|---------|
+| `acquire` | lease |
+| `closed` | no payload |
+| `expired` | topicShard |
+| `release` | payload object |
+| `renew` | lease |
+
+## 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 `topic-lease/v1`.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Integration: [`../../real_tests/integration/topic-lease-two-node.js`](../../../real_tests/integration/topic-lease-two-node.js)

scheduling-queues/hyper-p2p-topic-lease/docs/architecture.md

@@ -0,0 +1,44 @@
+# Architecture: hyper-p2p-topic-lease
+
+**Category:** Scheduling & queues
+
+```mermaid
+flowchart LR
+  App[Application] --> Mod[HyperP2PTopicLease]
+  Mod --> Mux[Protomux topic-lease/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 |
+|------|--------|-----------|----------|
+| `lease` | holder, lease, topicShard, type | gossip | Handled in onmessage / gossipSend |
+| `release` | holder, topicShard | 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-activity-queue`, `hyper-p2p-peer-scheduler`.
+

scheduling-queues/hyper-p2p-topic-lease/examples/basic.js

@@ -0,0 +1,12 @@
+require('bare-process/global')
+const { HyperP2PTopicLease } = require('../index.js')
+
+async function main () {
+  const l = new HyperP2PTopicLease()
+  console.log('acquire', l.acquire('shard-a'))
+  console.log('holder', l.holderOf('shard-a'))
+  l.release('shard-a')
+  await l.close()
+  console.log('done')
+}
+main().catch(console.error)

scheduling-queues/hyper-p2p-topic-lease/index.js

@@ -0,0 +1,117 @@
+require('bare-process/global')
+const EventEmitter = require('bare-events')
+const { setInterval, clearInterval } = require('bare-timers')
+const b4a = require('b4a')
+const { initModuleSwarm, gossipSend } = require('../../_shared/p2p-bare.js')
+
+const PROTOCOL = 'topic-lease/v1'
+const DEFAULT_LEASE_MS = 30000
+
+class HyperP2PTopicLease extends EventEmitter {
+  constructor (opts = {}) {
+    super()
+    this._stats = { ops: 0, errors: 0 }
+
+    this.topic = opts.topic || null
+    this.keyPair = opts.keyPair || require('hypercore-crypto').keyPair()
+    this.ownerHex = b4a.toString(this.keyPair.publicKey, 'hex')
+    this.leaseMs = opts.leaseMs ?? DEFAULT_LEASE_MS
+    this.enableBackgroundTimers = opts.enableBackgroundTimers === true
+    this._leases = new Map()
+    this._timer = null
+    this.swarm = null
+    this._peerMsgs = null
+  }
+
+  acquire (topicShard) {
+    const now = Date.now()
+    const current = this._leases.get(topicShard)
+    if (current && current.expiresAt > now && current.holder !== this.ownerHex) {
+      return { ok: false, holder: current.holder }
+    }
+    const lease = { topicShard, holder: this.ownerHex, acquiredAt: now, expiresAt: now + this.leaseMs }
+    this._leases.set(topicShard, lease)
+    if (this._peerMsgs) gossipSend(this, { type: 'lease', lease })
+    this.emit('acquire', lease)
+    return { ok: true, ...lease }
+  }
+
+  renew (topicShard) {
+    const lease = this._leases.get(topicShard)
+    if (!lease || lease.holder !== this.ownerHex) return false
+    lease.expiresAt = Date.now() + this.leaseMs
+    if (this._peerMsgs) gossipSend(this, { type: 'lease', lease })
+    this.emit('renew', lease)
+    return true
+  }
+
+  release (topicShard) {
+    const lease = this._leases.get(topicShard)
+    if (!lease || lease.holder !== this.ownerHex) return false
+    this._leases.delete(topicShard)
+    if (this._peerMsgs) gossipSend(this, { type: 'release', topicShard, holder: this.ownerHex })
+    this.emit('release', { topicShard })
+    return true
+  }
+
+  holder (topicShard) {
+    const lease = this._leases.get(topicShard)
+    if (!lease || lease.expiresAt < Date.now()) return null
+    return lease.holder
+  }
+
+  holderOf (topicShard) {
+    return this.holder(topicShard)
+  }
+
+  _expireSweep () {
+    const now = Date.now()
+    for (const [shard, lease] of this._leases) {
+      if (lease.expiresAt < now) {
+        this._leases.delete(shard)
+        this.emit('expired', { topicShard: shard })
+      }
+    }
+  }
+
+  async ready () {
+    if (this.swarm || !this.topic) return this
+    await initModuleSwarm(this, {
+      keyPair: this.keyPair,
+      topic: this.topic,
+      protocol: PROTOCOL,
+      onmessage: (data) => {
+        if (data && data.type === 'lease' && data.lease) {
+          const cur = this._leases.get(data.lease.topicShard)
+          if (!cur || data.lease.expiresAt > cur.expiresAt) {
+            this._leases.set(data.lease.topicShard, data.lease)
+          }
+        } else if (data && data.type === 'release') {
+          const cur = this._leases.get(data.topicShard)
+          if (cur && cur.holder === data.holder) this._leases.delete(data.topicShard)
+        }
+      }
+    })
+    if (this.enableBackgroundTimers && !this._timer) {
+      this._timer = setInterval(() => this._expireSweep(), 5000)
+    }
+    return this
+  }
+
+
+  getStats () {
+    return { ...this._stats }
+  }
+
+  async close () {
+    if (this._timer) {
+      clearInterval(this._timer)
+      this._timer = null
+    }
+    if (this.swarm) await this.swarm.destroy().catch(() => {})
+    this.swarm = null
+    this.emit('closed')
+  }
+}
+
+module.exports = { HyperP2PTopicLease, PROTOCOL }

scheduling-queues/hyper-p2p-topic-lease/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "hyper-p2p-topic-lease",
+  "version": "0.3.1",
+  "description": "Topic shard lease coordination for Bare/Pear P2P.",
+  "main": "index.js",
+  "type": "commonjs",
+  "license": "Apache-2.0",
+  "scripts": { "test": "brittle-bare test/test.js" },
+  "dependencies": {
+    "bare-events": "^2.8.0",
+    "bare-timers": "^2.0.0",
+    "bare-process": "^4.4.0",
+    "b4a": "^1.6.7",
+    "hypercore-crypto": "^3.0.0",
+    "protomux": "^3.0.0",
+    "compact-encoding": "^2.0.0"
+  },
+  "peerDependencies": { "hyperswarm": "^4.0.0", "bare": ">=1.0.0" },
+  "devDependencies": { "brittle": "^3.0.0" },
+  "imports": {
+    "process": { "bare": "bare-process", "default": "process" },
+    "events": { "bare": "bare-events", "default": "events" },
+    "timers": { "bare": "bare-timers", "default": "timers" }
+  }
+}

scheduling-queues/hyper-p2p-topic-lease/test/test.js

@@ -0,0 +1,26 @@
+require('bare-process/global')
+const test = require('brittle')
+const { HyperP2PTopicLease } = require('../index.js')
+
+test('topic-lease: acquire renew release', async (t) => {
+  const l = new HyperP2PTopicLease({ leaseMs: 60000 })
+  const r = l.acquire('shard-1')
+  t.ok(r.ok)
+  t.ok(l.renew('shard-1'))
+  t.is(l.holderOf('shard-1'), l.ownerHex)
+  t.ok(l.release('shard-1'))
+  t.is(l.holderOf('shard-1'), null)
+  await l.close()
+})
+
+test('topic-lease: no background timer default', async (t) => {
+  const l = new HyperP2PTopicLease()
+  t.is(l.enableBackgroundTimers, false)
+  t.is(l._timer, null)
+  await l.close()
+})
+test('hyper-p2p-topic-lease: close without leak', async (t) => {
+  const m = new HyperP2PTopicLease()
+  await m.close()
+  t.pass()
+})