ravenclaw/modules
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updates

Browse Source
This commit is contained in:
Raven Scott
2026-05-20 22:30:53 -04:00
parent e4400872c0
commit b8c335adee
89 changed files with 2862 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files
applications-collab/hyper-p2p-collab-room/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
applications-collab/hyper-p2p-collab-room/README.md
+30 -15
View File
@@ -1,28 +1,43 @@
# hyper-p2p-collab-room # hyper-p2p-collab-room
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `collab-room/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Collaboration room primitive. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyperconf` **Protocol:** `collab-room/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-presence` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PCollabRoom } = require('hyper-p2p-collab-room')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PCollabRoom({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/applications-collab/hyper-p2p-collab-room/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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/) — `collab-room-two-node.js`
## Test
```bash
npm install && npm test
```
applications-collab/hyper-p2p-collab-room/docs/api.md
+92 -13
View File
@@ -1,23 +1,102 @@
# hyper-p2p-collab-room API # API: hyper-p2p-collab-room
**Status:** scaffold · **Protocol:** `collab-room/v1` **Protocol:** `collab-room/v1`
## Class `HyperP2PCollabRoom` **Export:** `HyperP2PCollabRoom`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PCollabRoom(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `createRoom(roomId, meta = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `join(roomId, meta = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `leave(roomId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `broadcast(roomId, event)`
- **Returns:** `value`
- **Throws:**
- `Error: event object required`
- `Error: room not found`
### `getMembers(roomId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getEvents(roomId, limit = 50)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `broadcast` | roomId, event, remote |
| `closed` | no payload |
| `join` | payload object |
| `leave` | peer |
| `peer-joined` | roomId, member |
| `peer-left` | roomId, peer |
| `room-created` | payload object |
## 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 `collab-room/v1`.
## Testing
```bash
npm install && npm test
```
Integration: [`../../../real_tests/integration/collab-room-two-node.js`](../../../real_tests/integration/collab-room-two-node.js)
applications-collab/hyper-p2p-collab-room/docs/architecture.md
+38 -8
View File
@@ -1,15 +1,45 @@
# hyper-p2p-collab-room architecture # Architecture: hyper-p2p-collab-room
**Tier:** scaffold · **Category:** `applications-collab` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PCollabRoom]
Mod --> Mux[Protomux collab-room/v1]
Mux --> Swarm[Hyperswarm]
```
Collaboration room primitive. ## 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 |
|------|--------|-----------|----------|
| `broadcast` | event, roomId | gossip | Handled in onmessage / gossipSend |
| `join` | event, member, peer, roomId, type | gossip | Handled in onmessage / gossipSend |
| `leave` | event, peer, roomId, type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
applications-collab/hyper-p2p-cursor-presence/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
applications-collab/hyper-p2p-cursor-presence/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-cursor-presence # hyper-p2p-cursor-presence
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `cursor-presence/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Collaborative cursor presence. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyper-p2p-presence` **Protocol:** `cursor-presence/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-whiteboard-op` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PCursorPresence } = require('hyper-p2p-cursor-presence')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PCursorPresence({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/applications-collab/hyper-p2p-cursor-presence/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
applications-collab/hyper-p2p-cursor-presence/docs/api.md
+73 -13
View File
@@ -1,23 +1,83 @@
# hyper-p2p-cursor-presence API # API: hyper-p2p-cursor-presence
**Status:** scaffold · **Protocol:** `cursor-presence/v1` **Protocol:** `cursor-presence/v1`
## Class `HyperP2PCursorPresence` **Export:** `HyperP2PCursorPresence`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PCursorPresence(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `updateCursor(docId, position = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `getCursor(docId, peerHex)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `listCursors(docId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `removeCursor(docId, peerHex = this.peerHex)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `cursor` | entry |
| `remote-cursor` | data.entry |
## 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 `cursor-presence/v1`.
## Testing
```bash
npm install && npm test
```
applications-collab/hyper-p2p-cursor-presence/docs/architecture.md
+37 -8
View File
@@ -1,15 +1,44 @@
# hyper-p2p-cursor-presence architecture # Architecture: hyper-p2p-cursor-presence
**Tier:** scaffold · **Category:** `applications-collab` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PCursorPresence]
Mod --> Mux[Protomux cursor-presence/v1]
Mux --> Swarm[Hyperswarm]
```
Collaborative cursor presence. ## 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 |
|------|--------|-----------|----------|
| `cursor` | docId, entry, peer, type | gossip | Handled in onmessage / gossipSend |
| `cursor-remove` | docId, peer | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
applications-collab/hyper-p2p-document-line-lock/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
applications-collab/hyper-p2p-document-line-lock/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-document-line-lock # hyper-p2p-document-line-lock
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `document-line-lock/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Per-line document locks. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyper-p2p-distributed-lock` **Protocol:** `document-line-lock/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-whiteboard-op` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PDocumentLineLock } = require('hyper-p2p-document-line-lock')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PDocumentLineLock({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/applications-collab/hyper-p2p-document-line-lock/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
applications-collab/hyper-p2p-document-line-lock/docs/api.md
+75 -13
View File
@@ -1,23 +1,85 @@
# hyper-p2p-document-line-lock API # API: hyper-p2p-document-line-lock
**Status:** scaffold · **Protocol:** `document-line-lock/v1` **Protocol:** `document-line-lock/v1`
## Class `HyperP2PDocumentLineLock` **Export:** `HyperP2PDocumentLineLock`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PDocumentLineLock(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `acquire(docId, line)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `release(docId, line)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `isLocked(docId, line)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getLock(docId, line)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `acquire` | lock |
| `release` | payload object |
| `remote-acquire` | data.lock |
| `remote-release` | data |
## 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 `document-line-lock/v1`.
## Testing
```bash
npm install && npm test
```
applications-collab/hyper-p2p-document-line-lock/docs/architecture.md
+37 -8
View File
@@ -1,15 +1,44 @@
# hyper-p2p-document-line-lock architecture # Architecture: hyper-p2p-document-line-lock
**Tier:** scaffold · **Category:** `applications-collab` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PDocumentLineLock]
Mod --> Mux[Protomux document-line-lock/v1]
Mux --> Swarm[Hyperswarm]
```
Per-line document locks. ## 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 |
|------|--------|-----------|----------|
| `line-lock` | docId, line, lock, type | gossip | Handled in onmessage / gossipSend |
| `line-unlock` | docId, line | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
applications-collab/hyper-p2p-whiteboard-op/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
applications-collab/hyper-p2p-whiteboard-op/README.md
+30 -15
View File
@@ -1,28 +1,43 @@
# hyper-p2p-whiteboard-op # hyper-p2p-whiteboard-op
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `whiteboard-op/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Whiteboard operation CRDT. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyperdispatch` **Protocol:** `whiteboard-op/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-reactive-state` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PWhiteboardOp } = require('hyper-p2p-whiteboard-op')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PWhiteboardOp({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/applications-collab/hyper-p2p-whiteboard-op/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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/) — `whiteboard-op-two-node.js`
## Test
```bash
npm install && npm test
```
applications-collab/hyper-p2p-whiteboard-op/docs/api.md
+70 -13
View File
@@ -1,23 +1,80 @@
# hyper-p2p-whiteboard-op API # API: hyper-p2p-whiteboard-op
**Status:** scaffold · **Protocol:** `whiteboard-op/v1` **Protocol:** `whiteboard-op/v1`
## Class `HyperP2PWhiteboardOp` **Export:** `HyperP2PWhiteboardOp`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PWhiteboardOp(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `apply(roomId, op)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: op object required`
### `history(roomId, limit = 100)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `mergeRemote(entry)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `op` | remote |
## 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 `whiteboard-op/v1`.
## Testing
```bash
npm install && npm test
```
Integration: [`../../../real_tests/integration/whiteboard-op-two-node.js`](../../../real_tests/integration/whiteboard-op-two-node.js)
applications-collab/hyper-p2p-whiteboard-op/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-whiteboard-op architecture # Architecture: hyper-p2p-whiteboard-op
**Tier:** scaffold · **Category:** `applications-collab` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PWhiteboardOp]
Mod --> Mux[Protomux whiteboard-op/v1]
Mux --> Swarm[Hyperswarm]
```
Whiteboard operation CRDT. ## 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 |
|------|--------|-----------|----------|
| `wb-op` | entry | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
encoding-wire/hyper-p2p-compact-codec-bridge/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
encoding-wire/hyper-p2p-compact-codec-bridge/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-compact-codec-bridge # hyper-p2p-compact-codec-bridge
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `compact-codec-bridge/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Compact-encoding bridge. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `compact-encoding` **Protocol:** `compact-codec-bridge/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PCompactCodecBridge } = require('hyper-p2p-compact-codec-bridge')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PCompactCodecBridge({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/encoding-wire/hyper-p2p-compact-codec-bridge/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-compact-codec-bridge/docs/api.md
+62 -13
View File
@@ -1,23 +1,72 @@
# hyper-p2p-compact-codec-bridge API # API: hyper-p2p-compact-codec-bridge
**Status:** scaffold · **Protocol:** `compact-codec-bridge/v1` **Protocol:** `compact-codec-bridge/v1`
## Class `HyperP2PCompactCodecBridge` **Export:** `HyperP2PCompactCodecBridge`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PCompactCodecBridge(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
| `registry` | varies | new HyperP2PWireRegistry() | registry |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `encode(codecId, value)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `decode(codecId, buf)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
## 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 `compact-codec-bridge/v1`.
## Testing
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-compact-codec-bridge/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-compact-codec-bridge architecture # Architecture: hyper-p2p-compact-codec-bridge
**Tier:** scaffold · **Category:** `encoding-wire` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PCompactCodecBridge]
Mod --> Mux[Protomux compact-codec-bridge/v1]
Mux --> Swarm[Hyperswarm]
```
Compact-encoding bridge. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
encoding-wire/hyper-p2p-schema-validator/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
encoding-wire/hyper-p2p-schema-validator/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-schema-validator # hyper-p2p-schema-validator
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `schema-validator/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Schema validation for payloads. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyperschema` **Protocol:** `schema-validator/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PSchemaValidator } = require('hyper-p2p-schema-validator')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PSchemaValidator({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/encoding-wire/hyper-p2p-schema-validator/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-schema-validator/docs/api.md
+63 -13
View File
@@ -1,23 +1,73 @@
# hyper-p2p-schema-validator API # API: hyper-p2p-schema-validator
**Status:** scaffold · **Protocol:** `schema-validator/v1` **Protocol:** `schema-validator/v1`
## Class `HyperP2PSchemaValidator` **Export:** `HyperP2PSchemaValidator`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PSchemaValidator(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `register(name, schema)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: schema object required`
### `validate(name, value)`
- **Returns:** `value`
- **Throws:**
- `Error: unknown schema`
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
## 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 `schema-validator/v1`.
## Testing
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-schema-validator/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-schema-validator architecture # Architecture: hyper-p2p-schema-validator
**Tier:** scaffold · **Category:** `encoding-wire` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PSchemaValidator]
Mod --> Mux[Protomux schema-validator/v1]
Mux --> Swarm[Hyperswarm]
```
Schema validation for payloads. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
encoding-wire/hyper-p2p-wire-registry/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
encoding-wire/hyper-p2p-wire-registry/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-wire-registry # hyper-p2p-wire-registry
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `wire-registry/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Wire type registry. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `compact-encoding` **Protocol:** `wire-registry/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-protocol-handshake` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PWireRegistry } = require('hyper-p2p-wire-registry')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PWireRegistry({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/encoding-wire/hyper-p2p-wire-registry/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-wire-registry/docs/api.md
+90 -13
View File
@@ -1,23 +1,100 @@
# hyper-p2p-wire-registry API # API: hyper-p2p-wire-registry
**Status:** scaffold · **Protocol:** `wire-registry/v1` **Protocol:** `wire-registry/v1`
## Class `HyperP2PWireRegistry` **Export:** `HyperP2PWireRegistry`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PWireRegistry(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `registerCodec(id, codec)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: codec required`
### `registerProtocol(protocolId, meta = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `hasProtocol(protocolId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `encode(id, value)`
- **Returns:** `value`
- **Throws:**
- `Error: unknown codec id`
### `decode(id, buf)`
- **Returns:** `value`
- **Throws:**
- `Error: unknown codec id`
### `listProtocols(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `negotiate(offered = [])`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `protocol` | payload object |
## 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 `wire-registry/v1`.
## Testing
```bash
npm install && npm test
```
encoding-wire/hyper-p2p-wire-registry/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-wire-registry architecture # Architecture: hyper-p2p-wire-registry
**Tier:** scaffold · **Category:** `encoding-wire` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PWireRegistry]
Mod --> Mux[Protomux wire-registry/v1]
Mux --> Swarm[Hyperswarm]
```
Wire type registry. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-pubsub/hyper-p2p-qos-topic/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-pubsub/hyper-p2p-qos-topic/README.md
+30 -15
View File
@@ -1,28 +1,43 @@
# hyper-p2p-qos-topic # hyper-p2p-qos-topic
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `qos-topic/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
QoS tiers per topic. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `qos-topic/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-flow-shaper` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PQosTopic } = require('hyper-p2p-qos-topic')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PQosTopic({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-pubsub/hyper-p2p-qos-topic/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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/) — `qos-topic-two-node.js`
## Test
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-qos-topic/docs/api.md
+70 -13
View File
@@ -1,23 +1,80 @@
# hyper-p2p-qos-topic API # API: hyper-p2p-qos-topic
**Status:** scaffold · **Protocol:** `qos-topic/v1` **Protocol:** `qos-topic/v1`
## Class `HyperP2PQosTopic` **Export:** `HyperP2PQosTopic`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PQosTopic(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `subscribe(channel, handler, qos = 0)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: handler must be a function`
### `publish(channel, payload, opts = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `pending(qos)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `message` | msg |
## 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 `qos-topic/v1`.
## Testing
```bash
npm install && npm test
```
Integration: [`../../../real_tests/integration/qos-topic-two-node.js`](../../../real_tests/integration/qos-topic-two-node.js)
messaging-pubsub/hyper-p2p-qos-topic/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-qos-topic architecture # Architecture: hyper-p2p-qos-topic
**Tier:** scaffold · **Category:** `messaging-pubsub` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PQosTopic]
Mod --> Mux[Protomux qos-topic/v1]
Mux --> Swarm[Hyperswarm]
```
QoS tiers per topic. ## 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 |
|------|--------|-----------|----------|
| `qos-publish` | at, from, type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-pubsub/hyper-p2p-retained-messages/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-pubsub/hyper-p2p-retained-messages/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-retained-messages # hyper-p2p-retained-messages
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `retained-messages/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Retained message store. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `retained-messages/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PRetainedMessages } = require('hyper-p2p-retained-messages')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PRetainedMessages({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-pubsub/hyper-p2p-retained-messages/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-retained-messages/docs/api.md
+73 -13
View File
@@ -1,23 +1,83 @@
# hyper-p2p-retained-messages API # API: hyper-p2p-retained-messages
**Status:** scaffold · **Protocol:** `retained-messages/v1` **Protocol:** `retained-messages/v1`
## Class `HyperP2PRetainedMessages` **Export:** `HyperP2PRetainedMessages`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PRetainedMessages(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
| `maxPerChannel` | number | 32 | maxPerChannel |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `retain(channel, payload, meta = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `latest(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `list(channel, limit = 10)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `clear(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `retain` | payload object |
## 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 `retained-messages/v1`.
## Testing
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-retained-messages/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-retained-messages architecture # Architecture: hyper-p2p-retained-messages
**Tier:** scaffold · **Category:** `messaging-pubsub` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PRetainedMessages]
Mod --> Mux[Protomux retained-messages/v1]
Mux --> Swarm[Hyperswarm]
```
Retained message store. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-pubsub/hyper-p2p-subscription-lease/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-pubsub/hyper-p2p-subscription-lease/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-subscription-lease # hyper-p2p-subscription-lease
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `subscription-lease/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Subscription lease gossip. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `subscription-lease/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-topic-lease` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PSubscriptionLease } = require('hyper-p2p-subscription-lease')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PSubscriptionLease({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-pubsub/hyper-p2p-subscription-lease/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-subscription-lease/docs/api.md
+76 -13
View File
@@ -1,23 +1,86 @@
# hyper-p2p-subscription-lease API # API: hyper-p2p-subscription-lease
**Status:** scaffold · **Protocol:** `subscription-lease/v1` **Protocol:** `subscription-lease/v1`
## Class `HyperP2PSubscriptionLease` **Export:** `HyperP2PSubscriptionLease`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PSubscriptionLease(opts)
```
### `ready()` | 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) |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `acquire(channel)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `renew(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `release(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `holder(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **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` | channel |
## 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 `subscription-lease/v1`.
## Testing
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-subscription-lease/docs/architecture.md
+37 -8
View File
@@ -1,15 +1,44 @@
# hyper-p2p-subscription-lease architecture # Architecture: hyper-p2p-subscription-lease
**Tier:** scaffold · **Category:** `messaging-pubsub` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PSubscriptionLease]
Mod --> Mux[Protomux subscription-lease/v1]
Mux --> Swarm[Hyperswarm]
```
Subscription lease gossip. ## 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 |
|------|--------|-----------|----------|
| `sub-lease` | channel, hol, lease, type | gossip | Handled in onmessage / gossipSend |
| `sub-release` | channel, holder | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-pubsub/hyper-p2p-topic-channel/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-pubsub/hyper-p2p-topic-channel/README.md
+30 -15
View File
@@ -1,28 +1,43 @@
# hyper-p2p-topic-channel # hyper-p2p-topic-channel
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `topic-channel/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Named topic channels. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `topic-channel/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PTopicChannel } = require('hyper-p2p-topic-channel')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PTopicChannel({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-pubsub/hyper-p2p-topic-channel/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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-channel-two-node.js`
## Test
```bash
npm install && npm test
```
messaging-pubsub/hyper-p2p-topic-channel/docs/api.md
+81 -13
View File
@@ -1,23 +1,91 @@
# hyper-p2p-topic-channel API # API: hyper-p2p-topic-channel
**Status:** scaffold · **Protocol:** `topic-channel/v1` **Protocol:** `topic-channel/v1`
## Class `HyperP2PTopicChannel` **Export:** `HyperP2PTopicChannel`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PTopicChannel(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `subscribe(channel, handler)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: handler must be a function`
### `unsubscribe(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `publish(channel, payload, opts = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getRetained(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `syncRetained(channel)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `closed` | no payload |
| `message` | payload object |
## 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-channel/v1`.
## Testing
```bash
npm install && npm test
```
Integration: [`../../../real_tests/integration/topic-channel-two-node.js`](../../../real_tests/integration/topic-channel-two-node.js)
messaging-pubsub/hyper-p2p-topic-channel/docs/architecture.md
+36 -12
View File
@@ -1,22 +1,46 @@
# hyper-p2p-topic-channel architecture # Architecture: hyper-p2p-topic-channel
**Tier:** production · **Category:** `messaging-pubsub` · **Protocol:** `topic-channel/v1` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PTopicChannel]
Mod --> Mux[Protomux topic-channel/v1]
Mux --> Swarm[Hyperswarm]
```
Named topic channels over Hyperswarm + Protomux: subscribe, publish, optional retained messages per channel. ## 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 ## Wire messages
| type | Direction | Fields | | type | fields | direction | behavior |
|------|-----------|--------| |------|--------|-----------|----------|
| `subscribe` | gossip | `channel`, `peer` | | `publish` | at, channe, channel, payload, qos, retain, type | gossip | Handled in onmessage / gossipSend |
| `unsubscribe` | gossip | `channel`, `peer` | | `retained-sync` | at, channel, from, payload | gossip | Handled in onmessage / gossipSend |
| `publish` | gossip | `channel`, `payload`, `from`, `at`, `qos`, `retain` | | `subscribe` | peer, type | gossip | Handled in onmessage / gossipSend |
| `retained-sync` | gossip | `channel`, `payload`, `from`, `at` | | `unsubscribe` | peer, type | 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 ## Composition
Composes with `hyper-p2p-gossip-mesh`, `hyper-p2p-topic-lease`, `hyper-p2p-subscription-lease`. Composes with: see MODULE_CATEGORIES.md.
Uses `../../_shared/p2p-bare.js` (`initModuleSwarm`, `gossipSend`).
messaging-streams/hyper-p2p-stream-backpressure/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-backpressure/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stream-backpressure # hyper-p2p-stream-backpressure
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-backpressure/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Backpressure for P2P streams. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `stream-backpressure/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-flow-shaper` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStreamBackpressure } = require('hyper-p2p-stream-backpressure')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStreamBackpressure({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-backpressure/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-backpressure/docs/api.md
+82 -13
View File
@@ -1,23 +1,92 @@
# hyper-p2p-stream-backpressure API # API: hyper-p2p-stream-backpressure
**Status:** scaffold · **Protocol:** `stream-backpressure/v1` **Protocol:** `stream-backpressure/v1`
## Class `HyperP2PStreamBackpressure` **Export:** `HyperP2PStreamBackpressure`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStreamBackpressure(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
| `highWaterMark` | number | 65536 | highWaterMark |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `write(chunk)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: chunk required`
### `pause(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `resume(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `read(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `pending(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `backpressure` | bytes |
| `data` | buf |
| `pause` | no payload |
| `resume` | no payload |
## 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 `stream-backpressure/v1`.
## Testing
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-backpressure/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stream-backpressure architecture # Architecture: hyper-p2p-stream-backpressure
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStreamBackpressure]
Mod --> Mux[Protomux stream-backpressure/v1]
Mux --> Swarm[Hyperswarm]
```
Backpressure for P2P streams. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-streams/hyper-p2p-stream-chunker/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-chunker/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stream-chunker # hyper-p2p-stream-chunker
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-chunker/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Chunked stream framing. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyperbeam` **Protocol:** `stream-chunker/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-multipath-fanout` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStreamChunker } = require('hyper-p2p-stream-chunker')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStreamChunker({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-chunker/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-chunker/docs/api.md
+63 -13
View File
@@ -1,23 +1,73 @@
# hyper-p2p-stream-chunker API # API: hyper-p2p-stream-chunker
**Status:** scaffold · **Protocol:** `stream-chunker/v1` **Protocol:** `stream-chunker/v1`
## Class `HyperP2PStreamChunker` **Export:** `HyperP2PStreamChunker`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStreamChunker(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
| `chunkSize` | number | 4096 | chunkSize |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `push(data)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `flush(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `chunk` | tail |
## 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 `stream-chunker/v1`.
## Testing
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-chunker/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stream-chunker architecture # Architecture: hyper-p2p-stream-chunker
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStreamChunker]
Mod --> Mux[Protomux stream-chunker/v1]
Mux --> Swarm[Hyperswarm]
```
Chunked stream framing. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-streams/hyper-p2p-stream-multiplex/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-multiplex/README.md
+30 -15
View File
@@ -1,28 +1,43 @@
# hyper-p2p-stream-multiplex # hyper-p2p-stream-multiplex
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-multiplex/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Stream multiplex over mux. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `stream-multiplex/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { StreamHandle } = require('hyper-p2p-stream-multiplex')
const topic = process.argv[2] // 64-char hex or string
const mod = new StreamHandle({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-multiplex/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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/) — `stream-multiplex-two-node.js`
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-multiplex/docs/api.md
+89 -13
View File
@@ -1,23 +1,99 @@
# hyper-p2p-stream-multiplex API # API: hyper-p2p-stream-multiplex
**Status:** scaffold · **Protocol:** `stream-multiplex/v1` **Protocol:** `stream-multiplex/v1`
## Class `HyperP2PStreamMultiplex` **Export:** `StreamHandle`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new StreamHandle(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
| `highWaterMark` | number | 65536 | highWaterMark |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `write(chunk)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: stream closed`
### `end(chunk)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `ondata(fn)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `openStream(id = null)`
- **Returns:** `value`
- **Throws:**
- `Error: stream id already open`
### `receiveFrame(frame)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `closeStream(streamId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `closed` | no payload |
| `frame` | frame |
| `open` | streamId |
## 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 `stream-multiplex/v1`.
## Testing
```bash
npm install && npm test
```
Integration: [`../../../real_tests/integration/stream-multiplex-two-node.js`](../../../real_tests/integration/stream-multiplex-two-node.js)
messaging-streams/hyper-p2p-stream-multiplex/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-stream-multiplex architecture # Architecture: hyper-p2p-stream-multiplex
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[StreamHandle]
Mod --> Mux[Protomux stream-multiplex/v1]
Mux --> Swarm[Hyperswarm]
```
Stream multiplex over mux. ## 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 |
|------|--------|-----------|----------|
| `frame` | fin, type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-streams/hyper-p2p-stream-resume-token/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-resume-token/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stream-resume-token # hyper-p2p-stream-resume-token
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-resume-token/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Resume tokens for streams. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hypercore-byte-stream` **Protocol:** `stream-resume-token/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-session-bridge` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStreamResumeToken } = require('hyper-p2p-stream-resume-token')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStreamResumeToken({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-resume-token/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-resume-token/docs/api.md
+76 -13
View File
@@ -1,23 +1,86 @@
# hyper-p2p-stream-resume-token API # API: hyper-p2p-stream-resume-token
**Status:** scaffold · **Protocol:** `stream-resume-token/v1` **Protocol:** `stream-resume-token/v1`
## Class `HyperP2PStreamResumeToken` **Export:** `HyperP2PStreamResumeToken`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStreamResumeToken(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `write(chunk)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: chunk required`
### `checkpoint(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `resume(tokenId)`
- **Returns:** `value`
- **Throws:**
- `Error: unknown resume token`
### `readFromOffset(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `checkpoint` | token |
| `data` | buf |
| `resume` | token |
## 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 `stream-resume-token/v1`.
## Testing
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-resume-token/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stream-resume-token architecture # Architecture: hyper-p2p-stream-resume-token
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStreamResumeToken]
Mod --> Mux[Protomux stream-resume-token/v1]
Mux --> Swarm[Hyperswarm]
```
Resume tokens for streams. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-streams/hyper-p2p-stream-tee/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-tee/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stream-tee # hyper-p2p-stream-tee
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-tee/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Stream tee fan-out. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `stream-tee/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-distributed-event-bus` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStreamTee } = require('hyper-p2p-stream-tee')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStreamTee({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-tee/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-tee/docs/api.md
+74 -13
View File
@@ -1,23 +1,84 @@
# hyper-p2p-stream-tee API # API: hyper-p2p-stream-tee
**Status:** scaffold · **Protocol:** `stream-tee/v1` **Protocol:** `stream-tee/v1`
## Class `HyperP2PStreamTee` **Export:** `HyperP2PStreamTee`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStreamTee(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `addBranch(name)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: branch name required`
### `write(chunk)`
- **Returns:** `value`
- **Throws:**
- `Error: chunk required`
### `readBranch(name)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `pending(name)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `data` | buf |
## 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 `stream-tee/v1`.
## Testing
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-tee/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stream-tee architecture # Architecture: hyper-p2p-stream-tee
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStreamTee]
Mod --> Mux[Protomux stream-tee/v1]
Mux --> Swarm[Hyperswarm]
```
Stream tee fan-out. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
messaging-streams/hyper-p2p-stream-transform/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
messaging-streams/hyper-p2p-stream-transform/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stream-transform # hyper-p2p-stream-transform
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-transform/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Transform pipeline for streams. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `protomux` **Protocol:** `stream-transform/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-pattern-router` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStreamTransform } = require('hyper-p2p-stream-transform')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStreamTransform({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/messaging-streams/hyper-p2p-stream-transform/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-transform/docs/api.md
+74 -13
View File
@@ -1,23 +1,84 @@
# hyper-p2p-stream-transform API # API: hyper-p2p-stream-transform
**Status:** scaffold · **Protocol:** `stream-transform/v1` **Protocol:** `stream-transform/v1`
## Class `HyperP2PStreamTransform` **Export:** `HyperP2PStreamTransform`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStreamTransform(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `setTransform(fn)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: transform must be a function`
### `write(chunk)`
- **Returns:** `value`
- **Throws:**
- `Error: chunk required`
### `read(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `pending(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `data` | out |
## 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 `stream-transform/v1`.
## Testing
```bash
npm install && npm test
```
messaging-streams/hyper-p2p-stream-transform/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stream-transform architecture # Architecture: hyper-p2p-stream-transform
**Tier:** scaffold · **Category:** `messaging-streams` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStreamTransform]
Mod --> Mux[Protomux stream-transform/v1]
Mux --> Swarm[Hyperswarm]
```
Transform pipeline for streams. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
observability/hyper-p2p-health-probe/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
observability/hyper-p2p-health-probe/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-health-probe # hyper-p2p-health-probe
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `health-probe/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Health probe protocol. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyper-health-check` **Protocol:** `health-probe/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-presence` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PHealthProbe } = require('hyper-p2p-health-probe')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PHealthProbe({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/observability/hyper-p2p-health-probe/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
observability/hyper-p2p-health-probe/docs/api.md
+68 -13
View File
@@ -1,23 +1,78 @@
# hyper-p2p-health-probe API # API: hyper-p2p-health-probe
**Status:** scaffold · **Protocol:** `health-probe/v1` **Protocol:** `health-probe/v1`
## Class `HyperP2PHealthProbe` **Export:** `HyperP2PHealthProbe`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PHealthProbe(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `report(peerId, status = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `get(peerId)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `healthyPeers(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `remote-report` | data.entry |
| `report` | entry |
## 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 `health-probe/v1`.
## Testing
```bash
npm install && npm test
```
observability/hyper-p2p-health-probe/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-health-probe architecture # Architecture: hyper-p2p-health-probe
**Tier:** scaffold · **Category:** `observability` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PHealthProbe]
Mod --> Mux[Protomux health-probe/v1]
Mux --> Swarm[Hyperswarm]
```
Health probe protocol. ## 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 |
|------|--------|-----------|----------|
| `health` | type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
observability/hyper-p2p-health-probe/examples/basic.js
+3 -1
View File
@@ -3,6 +3,8 @@ const { HyperP2PHealthProbe } = require('../index.js')
async function main () { async function main () {
const m = new HyperP2PHealthProbe() const m = new HyperP2PHealthProbe()
console.log('[scaffold]', m.getStats()) m.report('peer-1', { ok: true, rttMs: 8 })
console.log('[health-probe]', m.getStats())
await m.close()
} }
main().catch(console.error) main().catch(console.error)
observability/hyper-p2p-log-gossip/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
observability/hyper-p2p-log-gossip/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-log-gossip # hyper-p2p-log-gossip
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `log-gossip/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Structured log gossip. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hypercore-logger` **Protocol:** `log-gossip/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PLogGossip } = require('hyper-p2p-log-gossip')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PLogGossip({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/observability/hyper-p2p-log-gossip/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
observability/hyper-p2p-log-gossip/docs/api.md
+65 -13
View File
@@ -1,23 +1,75 @@
# hyper-p2p-log-gossip API # API: hyper-p2p-log-gossip
**Status:** scaffold · **Protocol:** `log-gossip/v1` **Protocol:** `log-gossip/v1`
## Class `HyperP2PLogGossip` **Export:** `HyperP2PLogGossip`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PLogGossip(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
| `maxEntries` | number | 500 | maxEntries |
| `minLevel` | varies | 'debug' | minLevel |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `log(level, message, meta = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:** — (none documented in method body)
| TBD | gossip | Defined in implementation pass |
### `tail(limit = 50)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `log` | entry |
| `remote-log` | data.entry |
## 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 `log-gossip/v1`.
## Testing
```bash
npm install && npm test
```
observability/hyper-p2p-log-gossip/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-log-gossip architecture # Architecture: hyper-p2p-log-gossip
**Tier:** scaffold · **Category:** `observability` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PLogGossip]
Mod --> Mux[Protomux log-gossip/v1]
Mux --> Swarm[Hyperswarm]
```
Structured log gossip. ## 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 |
|------|--------|-----------|----------|
| `log` | type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
observability/hyper-p2p-log-gossip/examples/basic.js
+3 -1
View File
@@ -3,6 +3,8 @@ const { HyperP2PLogGossip } = require('../index.js')
async function main () { async function main () {
const m = new HyperP2PLogGossip() const m = new HyperP2PLogGossip()
console.log('[scaffold]', m.getStats()) m.log('info', 'example started')
console.log('[log-gossip]', m.tail(1))
await m.close()
} }
main().catch(console.error) main().catch(console.error)
observability/hyper-p2p-metrics-aggregator/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
observability/hyper-p2p-metrics-aggregator/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-metrics-aggregator # hyper-p2p-metrics-aggregator
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `metrics-aggregator/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Metrics aggregation gossip. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hyper-instrument` **Protocol:** `metrics-aggregator/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-congestion-signal` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PMetricsAggregator } = require('hyper-p2p-metrics-aggregator')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PMetricsAggregator({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/observability/hyper-p2p-metrics-aggregator/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
observability/hyper-p2p-metrics-aggregator/docs/api.md
+73 -13
View File
@@ -1,23 +1,83 @@
# hyper-p2p-metrics-aggregator API # API: hyper-p2p-metrics-aggregator
**Status:** scaffold · **Protocol:** `metrics-aggregator/v1` **Protocol:** `metrics-aggregator/v1`
## Class `HyperP2PMetricsAggregator` **Export:** `HyperP2PMetricsAggregator`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PMetricsAggregator(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | varies | null | topic |
| `keyPair` | KeyPair | random Ed25519 | keyPair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `record(name, value, labels = {})`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: metric name required`
- `Error: value must be a number`
### `summarize(name, labels = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `mergeRemote(name, value, labels = {})`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `exportAll(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
## 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 `metrics-aggregator/v1`.
## Testing
```bash
npm install && npm test
```
observability/hyper-p2p-metrics-aggregator/docs/architecture.md
+36 -8
View File
@@ -1,15 +1,43 @@
# hyper-p2p-metrics-aggregator architecture # Architecture: hyper-p2p-metrics-aggregator
**Tier:** scaffold · **Category:** `observability` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PMetricsAggregator]
Mod --> Mux[Protomux metrics-aggregator/v1]
Mux --> Swarm[Hyperswarm]
```
Metrics aggregation gossip. ## 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 |
|------|--------|-----------|----------|
| `metric` | at, type | 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
observability/hyper-p2p-metrics-aggregator/examples/basic.js
+3 -1
View File
@@ -3,6 +3,8 @@ const { HyperP2PMetricsAggregator } = require('../index.js')
async function main () { async function main () {
const m = new HyperP2PMetricsAggregator() const m = new HyperP2PMetricsAggregator()
console.log('[scaffold]', m.getStats()) m.record('latency_ms', 42)
console.log('[metrics]', m.summarize('latency_ms'))
await m.close()
} }
main().catch(console.error) main().catch(console.error)
observability/hyper-p2p-stats-exporter/CHANGELOG.md
+4
View File
@@ -3,3 +3,7 @@
## [0.0.0-scaffold] — Wave 8 ## [0.0.0-scaffold] — Wave 8
- Registry scaffold: file tree, load smoke tests, docs stubs - Registry scaffold: file tree, load smoke tests, docs stubs
## [0.3.2] - 2026-05-21
### Changed
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
observability/hyper-p2p-stats-exporter/README.md
+28 -15
View File
@@ -1,28 +1,41 @@
# hyper-p2p-stats-exporter # hyper-p2p-stats-exporter
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stats-exporter/v1` · **Wave:** 8 Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
Stats export format. **Category:** General
## Holepunch references (inspiration only) **Composes with:**
- `hypercore-stats` **Protocol:** `stats-exporter/v1`
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages. ## When to use
## Composes with Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-metrics-aggregator` ## When not to use
## Planned API Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair ## Quick start
- `getStats()` — scaffold counters
- `ready()` — no-op until implemented
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
## Layout ```js
const { HyperP2PStatsExporter } = require('hyper-p2p-stats-exporter')
const topic = process.argv[2] // 64-char hex or string
const mod = new HyperP2PStatsExporter({ topic, enableBackgroundTimers: false })
await mod.ready() // joins swarm when topic set
// ... application logic ...
await mod.close()
```
`modules/observability/hyper-p2p-stats-exporter/` ## Docs
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md). - [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
## Test
```bash
npm install && npm test
```
observability/hyper-p2p-stats-exporter/docs/api.md
+74 -13
View File
@@ -1,23 +1,84 @@
# hyper-p2p-stats-exporter API # API: hyper-p2p-stats-exporter
**Status:** scaffold · **Protocol:** `stats-exporter/v1` **Protocol:** `stats-exporter/v1`
## Class `HyperP2PStatsExporter` **Export:** `HyperP2PStatsExporter`
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier. ## Overview
### `constructor(opts?)` Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
### `getStats()` ## Constructor
Returns `{ created, errors, protocol, tier: 'scaffold' }`. ```js
const mod = new HyperP2PStatsExporter(opts)
```
### `ready()` | Option | Type | Default | Description |
|--------|------|---------|-------------|
| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
| `keyPair` | KeyPair | random | Ed25519 key pair |
Resolves immediately (no-op). ## Methods
## Wire (planned) ### `register(name, getStatsFn)`
| Message | Direction | Notes | - **Returns:** `value`
|---------|-----------|-------| - **Throws:**
| TBD | gossip | Defined in implementation pass | - `Error: getStatsFn required`
- `Error: name required`
### `unregister(name)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `snapshot(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `toJSON(—)`
- **Returns:** `value`
- **Throws:** — (none documented in method body)
### `getStats(—)`
- **Returns:** `object`
- **Throws:** — (none documented in method body)
### `ready(—)`
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
### `close(—)`
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
## Events
| Event | Payload |
|-------|---------|
| `snapshot` | out |
## 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 `stats-exporter/v1`.
## Testing
```bash
npm install && npm test
```
observability/hyper-p2p-stats-exporter/docs/architecture.md
+20 -8
View File
@@ -1,15 +1,27 @@
# hyper-p2p-stats-exporter architecture # Architecture: hyper-p2p-stats-exporter
**Tier:** scaffold · **Category:** `observability` **Category:** General
## Role ```mermaid
flowchart LR
App[Application] --> Mod[HyperP2PStatsExporter]
Mod --> Mux[Protomux stats-exporter/v1]
Mux --> Swarm[Hyperswarm]
```
Stats export format. ## 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 ## Composition
Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport. Composes with: see MODULE_CATEGORIES.md.
## Holepunch boundary
Inspiration: n/a
observability/hyper-p2p-stats-exporter/examples/basic.js
+3 -1
View File
@@ -3,6 +3,8 @@ const { HyperP2PStatsExporter } = require('../index.js')
async function main () { async function main () {
const m = new HyperP2PStatsExporter() const m = new HyperP2PStatsExporter()
console.log('[scaffold]', m.getStats()) m.register('demo', () => ({ ok: true }))
console.log('[stats-exporter]', m.snapshot())
await m.close()
} }
main().catch(console.error) main().catch(console.error)
observability/hyper-p2p-trace-span/examples/basic.js
+4 -1
View File
@@ -3,6 +3,9 @@ const { HyperP2PTraceSpan } = require('../index.js')
async function main () { async function main () {
const m = new HyperP2PTraceSpan() const m = new HyperP2PTraceSpan()
console.log('[scaffold]', m.getStats()) const id = m.startSpan('example')
m.endSpan(id)
console.log('[trace-span]', m.getStats())
await m.close()
} }
main().catch(console.error) main().catch(console.error)