Updates

2026-05-20 23:57:33 -04:00
parent ac60c93151
commit 226fca591d
86 changed files with 200 additions and 162 deletions
@@ -0,0 +1,87 @@
+# API: hyper-p2p-void-channel
+
+**Protocol:** `void-channel/v1` · **Export:** `HyperP2PVoidChannel`, `PROTOCOL`
+
+## Overview
+
+Experimental void-message channel: publishes void events per named `channel` with metadata, delivers to subscribers and gossips `void-publish` to peers.
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
+| `keyPair` | `KeyPair` | random | Identity |
+
+## Methods
+
+### `publishVoid(channel, meta?)`
+
+- **Returns:** `{ channel, meta, at, voided: true }`
+- **Throws:** `assertNonEmpty` on `channel`
+- **Gossip:** `{ type: 'void-publish', channel, meta, at }`
+- **Side effect:** `_deliver` to subscriber and `void` event
+
+### `subscribeVoid(channel, fn)`
+
+- **Returns:** unsubscribe function
+- **Throws:** `fn must be a function`
+- Replays last void for channel if present
+
+### `ready()` / `close()`
+
+`close` clears subscribers.
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `void` | void message object |
+| `closed` | — |
+
+## getStats()
+
+`published`, `received`, `subscriptions`, `gossipIn`, `gossipOut`, `channels` (subs size), `voids` (cache size), `protocol`.
+
+## Wire
+
+| type | fields | behavior |
+|------|--------|----------|
+| `void-publish` | `channel`, `meta`, `at` | Store and `_deliver` |
+
+## Errors
+
+`assertNonEmpty`, `fn must be a function`.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
+
+## P2P
+
+Void messages are idempotent per channel (latest stored in `_voids`).
+
+## Testing
+
+```bash
+cd modules/experimental/hyper-p2p-void-channel && npm test
+```
+
+## Composition
+
+Experimental wave5 modules; pair with `hyper-p2p-topic-announcer` for channel discovery.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## Remote merge rules
+
+- `void-publish` always updates `_voids` and calls `_deliver`
+- Subscriber `fn` errors are not caught on deliver (caller should guard)
+
+## Lifecycle
+
+Unsubscribe via function returned from `subscribeVoid`.
+
+## See also
+
+[`docs/architecture.md`](architecture.md), [`../../MODULE_CATEGORIES.md`](../../MODULE_CATEGORIES.md).
@@ -0,0 +1,18 @@
+# Architecture: hyper-p2p-void-channel
+
+**Protocol:** `void-channel/v1` · **Category:** experimental
+
+## Wire messages
+
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `void-publish` | gossip | `channel`, `meta`, `at` | Cache in `_voids`; deliver to subscriber |
+
+## State model
+
+- `_subs`: Map channel → callback
+- `_voids`: Map channel → last message
+
+## Composition
+
+`hyper-p2p-topic-announcer`, experimental wave5 peers.