Updates

experimental/hyper-p2p-memetic-spread/docs/api.md

@@ -0,0 +1,82 @@
+# API: hyper-p2p-memetic-spread
+
+**Protocol:** `memetic-spread/v1`
+
+**Export:** `{ HyperP2PMemeticSpread, PROTOCOL }`
+
+## Overview
+
+`HyperP2PMemeticSpread` tracks meme infection across peer ids: each `infect(memeId, peer)` adds a host and sets `strain` to host count (local) or max(remote strain, hosts).
+
+## Constructor
+
+```js
+const { HyperP2PMemeticSpread } = require('hyper-p2p-memetic-spread')
+const spread = new HyperP2PMemeticSpread({ topic: 'meme-mesh' })
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | string | `null` | Hyperswarm topic |
+| `keyPair` | KeyPair | random | Swarm identity |
+
+## Methods
+
+### `infect(memeId, peer) → { memeId, peer, strain }`
+
+- **Throws:** `assertNonEmpty` on `memeId`, `peer`
+- Gossips `meme-infect`; emits `infect`
+
+### `strain(memeId) → number`
+
+Host-set size for meme, or `0`.
+
+### `spreadStats() → object`
+
+`{ totalMemes, totalHosts, byMeme: { [id]: { strain, hosts } } }`
+
+### Lifecycle
+
+`ready()`, `close()` (emits `closed`), `getStats()`.
+
+## Meme record (internal)
+
+`{ memeId, hosts: Set, strain: number, firstSeen }`
+
+## P2P wire
+
+| type | fields |
+|------|--------|
+| `meme-infect` | `memeId`, `peer`, `strain`, `at` |
+
+## Events
+
+`infect`, `closed`
+
+## Strain semantics
+
+`strain` is recomputed as `hosts.size` after each local `infect`. Remote gossip uses `Math.max(local.strain, d.strain || hosts.size)` so the metric reflects reach, not viral velocity. `firstSeen` is set on first local observation only.
+
+## Selector patterns
+
+Use stable `memeId` strings (content hash, campaign id). Use `peer` as hex pubkey or logical agent id consistent across your mesh.
+
+## Limitations
+
+No decay or cure — hosts accumulate until process restart. For production epidemiology models, add TTL in your app layer.
+
+## Gossip payload
+
+`meme-infect` includes `at: Date.now()` from publisher; receivers do not rewrite timestamp.
+
+## Stats
+
+`getStats()` → `{ infections, gossipIn, gossipOut, memes, protocol }`.
+
+## Testing
+
+```bash
+npm install && npm test
+```
+
+Example: [`../examples/basic.js`](../examples/basic.js).

experimental/hyper-p2p-memetic-spread/docs/architecture.md

@@ -0,0 +1,17 @@
+# Architecture: hyper-p2p-memetic-spread
+
+**Category:** `experimental` · **Protocol:** `memetic-spread/v1`
+
+## Wire messages
+
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `meme-infect` | gossip | `memeId`, `peer`, `strain`, `at` | Union hosts; `strain = max(local, remote)` |
+
+## State model
+
+`_memes: Map(memeId → { hosts Set, strain, firstSeen })`
+
+## Composition
+
+Experimental analytics alongside `hyper-p2p-gossip-mesh` for fanout.