# Architecture: hyper-p2p-semantic-vector-index

**Category:** indexes-search  
**Protocol:** `hyper-p2p-semantic-vector-index/v1` (`SEMANTIC_PROTOCOL`)

## Purpose

Semantic embedding store with cosine top-k search, optional Ed25519 signing, 8-bit quantization, Hyperbee persistence, TTL pruning, and P2P `vector-insert` gossip.

## Components

```
HyperP2PSemanticVectorIndex
  ├── vectors: Map<id, entry>
  ├── tagIndex: Map<tag, Set<id>>
  ├── expiryQueue: Map<id, expiryTs>
  ├── optional hyperbee / swarm / vectorClock
  └── prune timer (bare-timers)
```

## Wire messages

| type | fields | direction | behavior |
|------|--------|-----------|----------|
| `vector-insert` | `id`, `entry` (metadata subset on gossip) | outbound on `insert` when `swarm` set; inbound via `_initP2P` / `receiveGossip` | Remote handler increments `gossipReceived`, emits `gossip-received`; full vector merge via `receiveGossip` |

Gossip send payload (lightweight):

```js
{ type: 'vector-insert', id, entry: { id, metadata, timestamp } }
```

`receiveGossip` accepts full `entry.vector` when present and verifies signature if enabled.

## Insert pipeline

1. L2-normalize vector to `options.dimension`
2. Build entry + optional `clockSnapshot`
3. `_signVector` when `enableSigning`
4. Store in `vectors`, index tags, schedule expiry
5. `_persistToHyperbee` if configured
6. `vectorClock.tick` if provided
7. `gossipSend` when `swarm` wired

## Search pipeline

Filter by tags, owner, timeRange → optional signature verify → cosine vs query → sort → top `k`.

## P2P topic derivation

`createP2PTopic(namespace)` hashes `SEMANTIC_PROTOCOL:namespace:localId`.

## Lifecycle

```
constructor → (optional _initP2P) → open() loads hyperbee
insert / search / pruneExpired → close()
```

## Composition

- `hyper-p2p-similarity-lsh` for candidate pre-filter
- `hyper-p2p-vector-clock` (optional) for causal snapshots
- `hyper-spatial-index` for geo metadata alongside embeddings

## Limits

- Linear scan search (no HNSW)
- `getStats()` returns `getMetrics()` plus `protocol` (same counters as `getMetrics()`)