feat: add novel hyper-p2p-intent-router v0.1.0 + workspace updates
- Created brand-new never-before-seen Bare/Pear module: hyper-p2p-intent-router
- Full production implementation: intent registration, Jaccard+keyword resolution, Protomux delivery, Hyperswarm discovery, Hyperbee persistence
- Complete test suite, examples, README, docs/architecture.md (Mermaid), docs/api.md
- Updated main README.md: added new module to Active Modules, marked as completed in roadmap, expanded This Run section with research study + full Node.js builtin scan (100% Bare compliant)
- Scanned all 8 modules for Node.js globals/builtins — no fixes needed
- Minor fixes in new module (constructor options, bootstrap handling)
- All work strictly inside /root/user-data/342128351638585344/projects/modules/
- Continuous autonomous novel primitive development
🤖 Autonomous Holepunch dev agent run
This commit is contained in:
Agent
@@ -0,0 +1,175 @@
|
||||
# API Reference — hyper-p2p-intent-router
|
||||
|
||||
## Class: HyperP2PIntentRouter
|
||||
|
||||
Extends `EventEmitter` from `bare-events`.
|
||||
|
||||
### Constructor
|
||||
|
||||
```js
|
||||
new HyperP2PIntentRouter(options)
|
||||
```
|
||||
|
||||
**Options**
|
||||
- `keyPair` — `{ publicKey, secretKey }` (default: random `bare-crypto` keyPair)
|
||||
- `storageDir` — Base directory for Hyperbee (default: `cwd + '/hyper-p2p-intent-router-storage'`)
|
||||
- `announceInterval` — ms between intent re-announcements (default: 60000)
|
||||
- `intentTTL` — ms until intent expires (default: 300000)
|
||||
- `maxIntentsPerPeer` — soft limit (default: 64)
|
||||
- `matchThreshold` — minimum score to return match (default: 0.3)
|
||||
- `bootstrap` — optional Hyperswarm bootstrap servers
|
||||
|
||||
### Methods
|
||||
|
||||
#### `async ready()`
|
||||
|
||||
Initializes storage, swarm, loads persisted intents, starts timers. Emits `'ready'`.
|
||||
|
||||
#### `async registerIntent(intentDef)`
|
||||
|
||||
Registers a new local intent.
|
||||
|
||||
**intentDef**
|
||||
```ts
|
||||
{
|
||||
id: string,
|
||||
description?: string,
|
||||
capabilities: string[],
|
||||
topics?: string[],
|
||||
metadata?: object,
|
||||
priority?: number
|
||||
}
|
||||
```
|
||||
|
||||
Returns `intentId` (string). Emits `'intent:registered'`.
|
||||
|
||||
#### `async unregisterIntent(intentId)`
|
||||
|
||||
Removes a local intent. Emits `'intent:unregistered'`.
|
||||
|
||||
#### `async resolveIntent(selector)`
|
||||
|
||||
Returns ranked array of matching intents (local + remote).
|
||||
|
||||
**selector**
|
||||
```ts
|
||||
{
|
||||
capabilities?: string[],
|
||||
keywords?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Return**
|
||||
```ts
|
||||
Array<{
|
||||
peerPublicKey: string,
|
||||
intent: Intent,
|
||||
score: number,
|
||||
lastSeen: number,
|
||||
local?: boolean
|
||||
}>
|
||||
```
|
||||
|
||||
Sorted descending by score.
|
||||
|
||||
#### `async sendToIntent(selector, payload, opts?)`
|
||||
|
||||
Resolves best match and delivers payload.
|
||||
|
||||
Returns `{ sent: boolean, peer?: string, local?: boolean, pending?: boolean, score?: number }`
|
||||
|
||||
Emits `'message:sent'` or throws if no match.
|
||||
|
||||
#### `getLocalIntents()`
|
||||
|
||||
Returns `Intent[]` of currently registered local intents.
|
||||
|
||||
#### `getPeerIntents(peerHex?)`
|
||||
|
||||
If `peerHex` provided: `Intent[]` for that peer.
|
||||
Otherwise: flattened `{ peer, ...intent }[]` for all known remote intents.
|
||||
|
||||
#### `async close()`
|
||||
|
||||
Graceful shutdown. Stops timers, destroys swarm, closes Hyperbee. Emits `'close'`.
|
||||
|
||||
### Events
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `ready` | — | Router fully initialized |
|
||||
| `intent:registered` | `Intent` | New local intent registered |
|
||||
| `intent:unregistered` | `string` (id) | Intent removed |
|
||||
| `intent:expired` | `string` (id) | Intent TTL reached |
|
||||
| `intent:announced` | `{intentId, topic}` | Intent topic joined |
|
||||
| `topic:joined` | `string` (hex) | Swarm topic active |
|
||||
| `peer:connected` | `{peerPublicKey}` | New peer connection |
|
||||
| `peer:disconnected` | `{peerPublicKey}` | Peer connection closed |
|
||||
| `intents:updated` | `{peer, count}` | Remote intents received/updated |
|
||||
| `message:received` | `{from, selector, payload}` | Routed routed message |
|
||||
| `message:sent` | `{peer, selector, payload}` | Outbound message delivered |
|
||||
| `message:local` | `{selector, payload, intent}` | Local self-delivery |
|
||||
| `peer:connect-request` | `{peerPublicKey, selector}` | Need to connect for pending send |
|
||||
| `error` | `Error` | Any internal error |
|
||||
|
||||
### Types
|
||||
|
||||
```ts
|
||||
interface Intent {
|
||||
id: string
|
||||
description: string
|
||||
capabilities: string[]
|
||||
topics: string[]
|
||||
metadata: object
|
||||
priority: number
|
||||
createdAt: number
|
||||
expiresAt: number
|
||||
}
|
||||
|
||||
interface IntentSelector {
|
||||
capabilities?: string[]
|
||||
keywords?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
### Constants
|
||||
|
||||
- `INTENT_PROTOCOL = 'hyper-p2p-intent-router/v1'`
|
||||
|
||||
## Example Usage Patterns
|
||||
|
||||
### Capability-First Discovery
|
||||
```js
|
||||
const matches = await router.resolveIntent({
|
||||
capabilities: ['gpu', 'cuda', 'stable-diffusion']
|
||||
})
|
||||
```
|
||||
|
||||
### Keyword + Priority Routing
|
||||
```js
|
||||
await router.sendToIntent({
|
||||
keywords: ['real-time', 'low-latency'],
|
||||
capabilities: ['inference']
|
||||
}, payload)
|
||||
```
|
||||
|
||||
### Reactive Updates
|
||||
```js
|
||||
router.on('intents:updated', ({ peer, count }) => {
|
||||
console.log(`${count} intents from ${peer}`)
|
||||
})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All async methods reject on fatal errors (storage, swarm). Non-fatal issues are emitted via `'error'`.
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- Intent maps are in-memory + persisted
|
||||
- Matching is O(n) over known intents (fine for < 10k intents)
|
||||
- Topic derivation is deterministic SHA256
|
||||
|
||||
---
|
||||
|
||||
*Complete API surface for the first production-grade intent routing primitive in the Bare ecosystem.*
|
||||
@@ -0,0 +1,154 @@
|
||||
# Architecture — hyper-p2p-intent-router
|
||||
|
||||
## Overview
|
||||
|
||||
`hyper-p2p-intent-router` provides a **declarative intent layer** on top of the Holepunch P2P stack. It turns raw peer discovery into semantic, capability-aware routing.
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph App["Application / AI Agent"]
|
||||
A1[Register Intent]
|
||||
A2[Resolve Intent]
|
||||
A3[SendToIntent]
|
||||
end
|
||||
|
||||
subgraph Router["HyperP2PIntentRouter"]
|
||||
R1[Intent Registry<br/>Map + Hyperbee]
|
||||
R2[Matcher<br/>Jaccard + Keyword]
|
||||
R3[Topic Deriver]
|
||||
R4[Connection Manager]
|
||||
end
|
||||
|
||||
subgraph P2P["P2P Layer"]
|
||||
P1[Hyperswarm<br/>Discovery]
|
||||
P2[Protomux<br/>Streaming]
|
||||
P3[Hyperbee<br/>Persistence]
|
||||
end
|
||||
|
||||
A1 --> R1
|
||||
A2 --> R2
|
||||
A3 --> R4
|
||||
R1 --> R3
|
||||
R3 --> P1
|
||||
R2 --> R1
|
||||
R2 --> P3
|
||||
R4 --> P2
|
||||
P1 <--> P2
|
||||
P2 <--> P3
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Intent Model
|
||||
- `id`: unique string
|
||||
- `capabilities`: string[] (exact match)
|
||||
- `description`: natural language
|
||||
- `topics`: string[]
|
||||
- `metadata`: arbitrary JSON
|
||||
- `priority`: numeric boost
|
||||
- `expiresAt`: TTL-based expiry
|
||||
|
||||
### 2. Matching Algorithm
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Selector["Selector {capabilities, keywords}"]
|
||||
Intent["Peer Intent"]
|
||||
Jaccard["Jaccard<br/>Similarity (0.6)"]
|
||||
Keyword["Keyword Overlap (0.4)"]
|
||||
Priority["Priority Boost"]
|
||||
Score["Final Score<br/>0..1"]
|
||||
|
||||
Selector --> Jaccard
|
||||
Intent --> Jaccard
|
||||
Selector --> Keyword
|
||||
Intent --> Keyword
|
||||
Jaccard --> Score
|
||||
Keyword --> Score
|
||||
Priority --> Score
|
||||
```
|
||||
|
||||
**Score calculation** (see `_computeMatchScore`):
|
||||
- Capability Jaccard: `|intersection| / |union|`
|
||||
- Keyword boost from description/topics
|
||||
- Normalized + priority multiplier
|
||||
|
||||
Threshold default: 0.3 (tunable)
|
||||
|
||||
### 3. Discovery & Gossip Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Local
|
||||
participant Swarm as Hyperswarm
|
||||
participant Remote
|
||||
participant Bee as Hyperbee
|
||||
|
||||
Local->>Local: registerIntent()
|
||||
Local->>Swarm: join(deriveTopic(intent))
|
||||
Local->>Bee: put(local:intentId)
|
||||
|
||||
Swarm-->>Remote: connection
|
||||
Remote->>Local: Protomux channel open
|
||||
Local->>Remote: intent-exchange (local intents)
|
||||
Remote->>Bee: put(peer:hex:intentId)
|
||||
Remote->>Local: intent-exchange (remote intents)
|
||||
|
||||
Note over Local,Remote: Future messages routed via best match
|
||||
```
|
||||
|
||||
### 4. Persistence & Lifecycle
|
||||
|
||||
- **Hyperbee** stores:
|
||||
- `local:<id>` → intent
|
||||
- `peer:<hex>:<id>` → remote intent snapshot
|
||||
- On restart: `_loadPersistedIntents()` rebuilds maps
|
||||
- Periodic cleanup removes expired intents
|
||||
- Graceful close: destroy swarm + close bee
|
||||
|
||||
### 5. Integration Points
|
||||
|
||||
- **With hyper-p2p-capabilities**: Register intents only after presenting valid capability tokens
|
||||
- **With hyper-p2p-vector-clock**: Attach vector clock to every intent message for causality
|
||||
- **With hyper-p2p-reactive-state**: Expose intent registry as observable CRDT
|
||||
- **With hyper-spatial-index**: Add `geo` filter to selector for location-aware routing
|
||||
|
||||
## Data Flow Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Register[registerIntent] --> Derive[deriveTopic + joinSwarm]
|
||||
Derive --> Announce[announce + persist]
|
||||
Announce --> Match[resolveIntent]
|
||||
|
||||
Resolve[resolveIntent] --> Score[computeMatchScore]
|
||||
Score --> Rank[sort by score]
|
||||
Rank --> Return[return top matches]
|
||||
|
||||
Send[sendToIntent] --> Resolve
|
||||
Resolve --> Connect[ensure Protomux connection]
|
||||
Connect --> Stream[createStream + send payload]
|
||||
|
||||
Connection[on connection] --> Exchange[exchangeIntents]
|
||||
Exchange --> UpdatePeer[update peerIntents Map]
|
||||
UpdatePeer --> Emit[emit intents:updated]
|
||||
```
|
||||
|
||||
## Security & Trust
|
||||
|
||||
- Intents are self-declared (trust via higher layer: hyper-p2p-capabilities + signatures)
|
||||
- No built-in auth — compose with capability proofs
|
||||
- All wire data is Buffer/JSON over encrypted Hyperswarm connections
|
||||
|
||||
## Future Extensions (v0.2+)
|
||||
|
||||
- Vector embeddings for true semantic similarity
|
||||
- Intent delegation / proxying
|
||||
- Byzantine-tolerant intent consensus
|
||||
- Cross-intent composition (AND/OR graphs)
|
||||
|
||||
---
|
||||
|
||||
*This architecture was designed to be the foundational routing layer for next-generation intent-centric P2P applications on Bare/Pear.*
|
||||
Reference in New Issue
Block a user