@sym-bot/sym 0.1.0 → 0.2.0

package/docs/p2p-protocol-research.md

@@ -0,0 +1,907 @@
+# P2P Protocol Research for AI Agent Mesh Networks
+
+Research conducted: 2026-03-23
+
+---
+
+## 1. libp2p (IPFS, Filecoin, Ethereum)
+
+**What it is:** A modular networking stack extracted from IPFS. Provides building blocks for P2P applications: transports, peer discovery, content routing, NAT traversal, pubsub.
+
+### Core Design Principles
+- **Unix philosophy:** Small, composable, swappable modules
+- **Transport agnostic:** TCP, QUIC, WebSocket, WebRTC, WebTransport all supported
+- **Identity-centric:** Every peer has a cryptographic identity (PeerId derived from public key)
+- **Protocol negotiation:** Peers negotiate which protocols they support at connection time
+
+### Discovery Mechanism
+- **Kademlia DHT** for wide-area peer discovery
+- **mDNS** for local network discovery (LAN)
+- **Bootstrap nodes** as initial entry points
+- **Rendezvous protocol** for topic-based discovery
+
+### Transport Model
+- Multi-transport: TCP, QUIC, WebSocket, WebRTC, WebTransport
+- Connections upgraded to secure channels via TLS 1.3 or Noise protocol
+- Stream multiplexing over single connections (yamux, mplex)
+- NAT traversal via relay nodes (Circuit Relay v2) and hole punching
+
+### Message Format
+- Protocol Buffers for wire format
+- Multiaddr for addressing (self-describing network addresses)
+- GossipSub for pubsub (mesh + gossip hybrid)
+
+### State Synchronization
+- No built-in state sync — delegates to application layer
+- Kademlia DHT for distributed key-value lookups
+- GossipSub for real-time message propagation
+- Bitswap for content exchange (IPFS-specific)
+
+### Offline/Reconnect Behavior
+- DHT routing tables gradually evict unresponsive peers via periodic PING
+- Peers re-announce themselves on reconnection
+- No built-in message queuing for offline peers
+- Relay nodes can bridge connectivity gaps
+
+### Central vs P2P
+- **Fully P2P** in design, but practically relies on bootstrap nodes and relay infrastructure
+- No central authority; any node can serve any role
+
+### Tradeoffs
+- (+) Extremely modular and extensible
+- (+) Battle-tested at scale (IPFS, Filecoin, Ethereum)
+- (+) Rich NAT traversal capabilities
+- (-) Complexity — many moving parts to configure
+- (-) No built-in offline message delivery
+- (-) DHT can be slow for real-time discovery
+
+### Key Lessons for Agent Mesh
+- **Modularity is essential** — agents may run on different platforms with different transport capabilities
+- **PeerId as cryptographic identity** is the right model for agent identity
+- **GossipSub** is an excellent pubsub model for topic-based agent communication
+- **Circuit Relay** pattern solves NAT traversal without requiring all agents to be publicly reachable
+
+---
+
+## 2. Matrix Protocol
+
+**What it is:** An open standard for decentralized, federated real-time communication. Each user connects to a homeserver; homeservers federate with each other.
+
+### Core Design Principles
+- **Decentralized conversation history** — no single server owns the truth
+- **Eventual consistency** via event DAGs
+- **Federation** — servers replicate room state to each other
+- **End-to-end encryption** (Megolm/Olm) as first-class feature
+
+### Discovery Mechanism
+- Users are addressed as `@user:homeserver.org`
+- Room aliases (`#room:server`) resolve to room IDs via server lookups
+- Server discovery via `.well-known` DNS records and SRV records
+- Room directory for public room discovery
+
+### Transport Model
+- Client-Server API: RESTful HTTP + JSON (long-polling or SSE for sync)
+- Server-Server (Federation) API: HTTPS with signed JSON
+- All events are cryptographically signed by originating server
+
+### Message Format
+- JSON events with standardized schema
+- Each event has: type, content, sender, room_id, origin_server_ts, event_id
+- State events have additional `state_key` field
+- Events form a DAG (Directed Acyclic Graph) — each references parent events
+
+### State Synchronization
+- **Event DAG:** Each event references its parent events, forming a partial order
+- **State Resolution Algorithm (v2):** Deterministic algorithm to resolve conflicts when servers have divergent views of room state
+- **Backfill:** Servers can request missing events from other servers in the room
+- Events are signed and immutable — append-only log per room
+
+### Offline/Reconnect Behavior
+- Homeserver stores all events while user is offline
+- Client syncs via `/sync` endpoint with a `since` token — gets all missed events
+- Federation: servers backfill from peers when they come back online
+- **Strong offline support** — the homeserver acts as a persistent store-and-forward relay
+
+### Central vs P2P
+- **Federated** — each homeserver is a central point for its users, but no global center
+- Experimental P2P Matrix (Pinecone) removes the homeserver requirement
+- In practice, matrix.org is a dominant homeserver
+
+### Tradeoffs
+- (+) Excellent offline handling — homeserver stores everything
+- (+) Rich state model with conflict resolution
+- (+) E2E encryption built in
+- (+) Bridges to other protocols (Slack, IRC, etc.)
+- (-) Homeservers are resource-intensive (Synapse is notoriously heavy)
+- (-) State resolution can be complex and expensive
+- (-) Federation has trust/moderation challenges
+- (-) Event DAG grows indefinitely
+
+### Key Lessons for Agent Mesh
+- **Event DAG** is a powerful model for ordering agent interactions
+- **State resolution** is critical when agents have divergent views
+- **Homeserver-as-proxy** pattern solves mobile background restrictions — agent has a persistent relay
+- **Room model** maps well to agent collaboration spaces
+- **Backfill** mechanism is exactly what agents need for catching up after being offline
+
+---
+
+## 3. Nostr (Notes and Other Stuff Transmitted by Relays)
+
+**What it is:** A minimalist protocol for decentralized social networking. Clients publish signed events to relays; relays store and serve events.
+
+### Core Design Principles
+- **Radical simplicity** — the protocol is tiny (NIP-01 is a few pages)
+- **User identity = keypair** (secp256k1). No registration, no usernames, no servers to trust
+- **Relays are dumb storage** — they store events and serve them on request
+- **Client intelligence** — all logic lives in the client
+- **Censorship resistance** — users can publish to multiple relays
+
+### Discovery Mechanism
+- Users publish a "relay list" event (NIP-65) declaring which relays they use
+- Clients query multiple relays to find a user's events
+- No global directory — discovery is organic via relay overlap
+- NIP-05: DNS-based identity verification (user@domain.com mapping)
+
+### Transport Model
+- **WebSocket** connections between client and relay
+- Simple JSON messages over WebSocket:
+  - `["EVENT", <event>]` — publish
+  - `["REQ", <sub_id>, <filters>]` — subscribe/query
+  - `["CLOSE", <sub_id>]` — unsubscribe
+
+### Message Format
+- Single event type with fields: `id`, `pubkey`, `created_at`, `kind`, `tags`, `content`, `sig`
+- `kind` integer determines event semantics (0=metadata, 1=text note, 4=DM, etc.)
+- Tags provide structured metadata: `["e", <event_id>]`, `["p", <pubkey>]`
+- Events are signed with Schnorr signatures
+
+### State Synchronization
+- **No sync protocol** — relays are independent and may have different events
+- Clients query multiple relays and merge results client-side
+- "Replaceable events" (NIP-16): newer event of same kind+pubkey replaces older
+- "Parameterized replaceable events": newer event of same kind+pubkey+d-tag replaces older
+- No conflict resolution beyond "latest timestamp wins"
+
+### Offline/Reconnect Behavior
+- Events persist on relays indefinitely (relay policy permitting)
+- Client reconnects and re-subscribes; gets current state from relay
+- No guaranteed delivery — if a relay was down when event was published, it may never get it
+- Users mitigate by publishing to multiple relays
+
+### Central vs P2P
+- **Neither federated nor P2P** — it's a novel "relay" architecture
+- Relays are independent servers; clients choose which relays to use
+- No relay-to-relay communication (by default)
+- Users are sovereign; relays are interchangeable infrastructure
+
+### Tradeoffs
+- (+) Extreme simplicity — easy to implement
+- (+) User sovereignty — identity is just a keypair
+- (+) Censorship resistant — multi-relay redundancy
+- (+) No complex state sync needed
+- (-) No guaranteed delivery
+- (-) Relay discovery can be unreliable
+- (-) No built-in E2E encryption (NIP-44 adds it optionally)
+- (-) Spam management is relay-by-relay
+- (-) "Latest timestamp wins" is a weak conflict resolution
+
+### Key Lessons for Agent Mesh
+- **Simplicity wins** — Nostr's adoption grew fast because the protocol is trivial to implement
+- **Keypair identity** removes all registration/discovery overhead
+- **Multi-relay redundancy** is a powerful pattern for resilience
+- **"Dumb relay, smart client"** maps well to "dumb infrastructure, smart agent"
+- **Event-based model** with kinds is highly extensible
+- **Replaceable events** pattern works well for agent state announcements
+
+---
+
+## 4. MQTT (Message Queuing Telemetry Transport)
+
+**What it is:** A lightweight publish/subscribe messaging protocol designed for constrained devices and unreliable networks. OASIS standard.
+
+### Core Design Principles
+- **Minimal overhead** — 2-byte fixed header minimum
+- **Pub/sub decoupling** — publishers and subscribers don't know about each other
+- **Quality of Service levels** — flexible delivery guarantees
+- **Designed for unreliable networks** — built-in keepalive, will messages, session persistence
+
+### Discovery Mechanism
+- **No peer discovery** — broker-centric architecture
+- Clients connect to a known broker endpoint
+- Topic-based routing — subscribers discover publishers by subscribing to topics
+- Wildcard subscriptions (`+` single level, `#` multi-level)
+
+### Transport Model
+- TCP-based (MQTT 3.1.1)
+- MQTT 5.0 adds enhanced features (reason codes, shared subscriptions, topic aliases)
+- MQTT-SN variant for UDP/non-TCP transports (sensor networks)
+- TLS for encryption
+- WebSocket transport available
+
+### Message Format
+- Binary protocol with compact fixed header (2 bytes minimum)
+- Variable header and payload depend on packet type
+- 14 packet types: CONNECT, CONNACK, PUBLISH, PUBACK, SUBSCRIBE, etc.
+- Topic strings (UTF-8) for routing
+- Payload is opaque bytes — any format
+
+### State Synchronization
+- **No state sync** — MQTT is purely a message transport
+- **Retained messages:** Last message on a topic is stored and delivered to new subscribers
+- **Persistent sessions:** Broker stores subscriptions and queued QoS 1/2 messages for disconnected clients
+- **Last Will and Testament (LWT):** Broker publishes a pre-configured message when client disconnects unexpectedly
+
+### Offline/Reconnect Behavior
+- **Persistent sessions** (Clean Session = false): Broker queues messages while client is offline
+- On reconnect, client receives all queued QoS 1/2 messages
+- QoS 0: At most once (fire and forget) — lost if offline
+- QoS 1: At least once — queued and retried
+- QoS 2: Exactly once — queued with full handshake
+- **Session Expiry Interval** (MQTT 5.0): configurable session lifetime
+
+### Central vs P2P
+- **Centralized broker** — all messages flow through the broker
+- Broker clustering for HA (vendor-specific)
+- Not P2P at all; the broker is the single point of coordination
+
+### Tradeoffs
+- (+) Extremely lightweight — runs on microcontrollers
+- (+) Excellent offline handling with persistent sessions
+- (+) QoS levels provide flexible delivery guarantees
+- (+) Retained messages provide "current state" semantics
+- (+) Wildcard subscriptions enable flexible topic hierarchies
+- (+) LWT provides presence/failure notification
+- (-) Central broker is a single point of failure
+- (-) No peer discovery
+- (-) No built-in encryption at protocol level (relies on TLS)
+- (-) Topic-based only — no content-based routing
+
+### Key Lessons for Agent Mesh
+- **QoS levels** are essential for agent communication — some messages must be guaranteed, others are fire-and-forget
+- **Retained messages** pattern is perfect for agent state/capability announcements
+- **Last Will and Testament** is an elegant offline detection mechanism
+- **Persistent sessions** solve the mobile background problem — broker stores messages
+- **Topic hierarchies with wildcards** are a natural fit for agent capability routing
+- **2-byte overhead** shows how minimal a protocol can be
+
+---
+
+## 5. WebRTC (Web Real-Time Communication)
+
+**What it is:** A set of protocols and APIs for real-time peer-to-peer communication of audio, video, and data directly between browsers/apps.
+
+### Core Design Principles
+- **Direct peer-to-peer** communication (no intermediary for media)
+- **NAT traversal as core requirement** — ICE framework
+- **Secure by default** — DTLS mandatory
+- **Codec negotiation** via SDP (Session Description Protocol)
+- **Signaling is out of scope** — protocol only handles media/data transport
+
+### Discovery Mechanism
+- **No built-in discovery** — requires external signaling server
+- Signaling exchanges SDP offers/answers and ICE candidates
+- Signaling can use any transport (WebSocket, HTTP, even QR codes)
+- ICE candidates gathered from: local interfaces, STUN servers, TURN servers
+
+### Transport Model
+- **ICE (Interactive Connectivity Establishment):** Tests multiple connection paths, picks best
+- **STUN:** Discovers public IP/port; enables direct connection through NAT
+- **TURN:** Relay fallback when direct connection impossible (~10-15% of connections)
+- **DTLS:** Encryption over UDP
+- **SRTP:** Encrypted real-time media
+- **DataChannels:** Reliable or unreliable data over SCTP/DTLS
+
+### Message Format
+- SDP (Session Description Protocol) for negotiation — text-based
+- RTP/SRTP for media streams
+- SCTP for data channels — supports binary and text
+- DataChannels can be configured as ordered/unordered, reliable/unreliable
+
+### State Synchronization
+- **No state sync** — WebRTC is a transport, not a state system
+- DataChannels provide raw bidirectional communication
+- Application must implement its own state sync over DataChannels
+
+### Offline/Reconnect Behavior
+- **Connection is lost** when peer goes offline — ICE connection fails
+- **ICE restart** can attempt to re-establish connection with new candidates
+- No message queuing or store-and-forward
+- Requires signaling server to coordinate reconnection
+
+### Central vs P2P
+- **P2P for data/media transport** — direct peer connections
+- **Requires signaling server** for connection setup (not fully P2P)
+- **TURN relay** as fallback makes it partially client-server
+- In practice: hybrid architecture
+
+### Tradeoffs
+- (+) True P2P data transfer — low latency
+- (+) Excellent NAT traversal (ICE/STUN/TURN)
+- (+) Built into every modern browser
+- (+) DataChannels support both reliable and unreliable modes
+- (+) Mandatory encryption
+- (-) Requires signaling infrastructure
+- (-) Connection setup is complex and slow (ICE gathering)
+- (-) No offline message delivery
+- (-) Peer-to-peer doesn't scale beyond small groups (mesh topology)
+- (-) Maintaining connections drains mobile battery
+
+### Key Lessons for Agent Mesh
+- **ICE framework** is the gold standard for NAT traversal
+- **DataChannels** provide flexible transport (reliable/unreliable, ordered/unordered)
+- **Signaling is separate from transport** — good architectural separation
+- **Direct P2P is ideal for latency-sensitive agent communication** (real-time sensing)
+- **TURN relay pattern** is essential fallback — not all agents can connect directly
+- **Connection setup overhead** means WebRTC is better for persistent connections than one-off messages
+
+---
+
+## 6. Kademlia DHT
+
+**What it is:** A distributed hash table protocol that uses XOR distance metric for efficient peer lookup and content routing. Used by BitTorrent, IPFS, Ethereum.
+
+### Core Design Principles
+- **XOR distance metric** — distance = XOR of node IDs, interpreted as integer
+- **Logarithmic lookup** — O(log n) hops to find any node/value
+- **Self-organizing** — routing tables maintained through normal traffic
+- **Redundancy** — values stored on k closest nodes (typically k=20)
+
+### Discovery Mechanism
+- **Bootstrap:** New node needs address of just ONE existing node
+- **Self-lookup:** New node performs a lookup on its own ID to populate routing table
+- **k-buckets:** Routing table organized by XOR distance ranges; each bucket holds up to k entries
+- **Bucket refresh:** Periodic lookups on random IDs within each bucket's range
+
+### Transport Model
+- UDP-based RPC (original paper)
+- Four RPCs: PING, STORE, FIND_NODE, FIND_VALUE
+- Implementations vary (libp2p uses TCP+multiplexing)
+
+### Message Format
+- Simple RPC messages containing: sender node ID, target ID, and payload
+- Responses include closest known nodes to target
+
+### State Synchronization
+- **Key-value store:** Values stored on k closest nodes to key
+- **Republishing:** Values periodically re-stored to maintain redundancy
+- **No conflict resolution** — last write wins or application-defined
+- **Expiration:** Values expire after configurable TTL
+
+### Offline/Reconnect Behavior
+- **Graceful degradation:** k-bucket entries are evicted only after confirmed failure (PING timeout)
+- **Preference for long-lived nodes:** Existing entries preferred over new ones (stability heuristic)
+- **Automatic recovery:** Rejoining node performs self-lookup, quickly rebuilds routing table
+- **Redundancy covers gaps:** k replicas ensure availability even when some nodes are offline
+
+### Central vs P2P
+- **Fully P2P** — no central coordination
+- Bootstrap nodes are the only "well-known" infrastructure
+- All nodes are equal participants
+
+### Tradeoffs
+- (+) Proven at massive scale (millions of nodes in BitTorrent)
+- (+) O(log n) lookup efficiency
+- (+) Self-healing — network adapts to churn automatically
+- (+) Preference for stable nodes reduces routing table churn
+- (-) Lookup latency (multiple round trips)
+- (-) Vulnerable to Sybil attacks (attacker creates many node IDs)
+- (-) Eclipse attacks (surrounding a target with malicious nodes)
+- (-) Not suitable for real-time communication
+- (-) Bootstrap node dependency for initial join
+
+### Key Lessons for Agent Mesh
+- **XOR distance** is an elegant, symmetric distance metric — useful for agent capability routing
+- **k-bucket structure** naturally maintains a balanced view of the network
+- **Preference for long-lived nodes** is smart — stable agents should be preferred routing partners
+- **Self-lookup on join** is an efficient bootstrapping pattern
+- **k-redundancy** ensures resilience without coordination
+- **Not suitable as sole discovery mechanism** for real-time agent communication — too slow
+
+---
+
+## 7. Gossip Protocols (SWIM, HyParView)
+
+### SWIM (Scalable Weakly-consistent Infection-style Process Group Membership)
+
+**What it is:** A protocol for membership management and failure detection in large distributed systems. Used by Consul, Serf (HashiCorp).
+
+#### Core Design Principles
+- **Separate failure detection from dissemination** — two distinct components
+- **Randomized probing** — each node randomly selects one peer per round to probe
+- **Piggyback dissemination** — membership updates ride on failure detection messages
+- **Suspicion before declaration** — nodes are suspected before declared dead
+
+#### Discovery Mechanism
+- Join via any known member
+- Membership list propagated via gossip (piggyback on ping/ack)
+- New member announced infection-style through the cluster
+
+#### How It Works
+1. Each period: node picks random peer, sends PING
+2. If no ACK: sends PING-REQ to k random peers (indirect probe)
+3. If still no ACK: marks peer as SUSPECTED
+4. Suspected peers get grace period before being declared DEAD
+5. Membership changes (join/leave/fail) piggyback on ping/ack messages
+
+#### Scalability
+- O(1) message load per member per period (constant, not proportional to cluster size)
+- Compared to heartbeat protocols: O(n^2) vs O(n) total messages
+- Infection-style dissemination reaches all nodes in O(log n) rounds
+
+### HyParView
+
+**What it is:** A membership protocol designed specifically for reliable gossip-based broadcast.
+
+#### Core Design Principles
+- **Two partial views:** Small active view (log(n)+c peers) + larger passive view (k*(log(n)+c) peers)
+- **Active view = overlay network** — broadcast is flooding over active view connections
+- **Passive view = backup pool** — nodes promoted to active when active members fail
+- **TCP-based** — connections double as failure detectors
+
+#### How It Works
+- Active view maintained via TCP connections — broken connection = immediate failure detection
+- Passive view maintained via periodic shuffle (random exchange of partial views)
+- When active member fails: promote random passive member
+- Recovers from up to 80% node failure while maintaining broadcast reliability
+
+### Tradeoffs (Both)
+- (+) Scalable failure detection (SWIM: constant overhead per node)
+- (+) Fast dissemination (logarithmic rounds)
+- (+) Resilient to high failure rates (HyParView: survives 80% failure)
+- (+) No central coordinator
+- (-) Eventual consistency — membership view may be temporarily inconsistent
+- (-) False positives possible (mitigated by suspicion mechanism)
+- (-) Requires continuous background traffic
+
+### Key Lessons for Agent Mesh
+- **SWIM's piggyback pattern** is brilliant — reuse existing messages for metadata propagation
+- **Suspicion mechanism** is essential — avoid declaring agents dead prematurely
+- **HyParView's dual-view** approach balances active communication with fault tolerance
+- **Infection-style dissemination** is ideal for propagating agent capability updates
+- **O(1) per-member overhead** is critical for mobile agents with limited resources
+- **TCP as failure detector** (HyParView) is practical and efficient
+
+---
+
+## 8. CRDTs (Conflict-Free Replicated Data Types)
+
+**What it is:** Data structures that can be replicated across multiple nodes and updated independently, with a mathematically guaranteed merge that always converges to the same state.
+
+### Core Design Principles
+- **Strong eventual consistency** — all replicas that have received the same set of updates converge to the same state
+- **No coordination needed** — updates applied locally without consensus
+- **Merge must be commutative, associative, and idempotent** (forms a join-semilattice)
+- **Two flavors:** State-based (CvRDT) and Operation-based (CmRDT)
+
+### Types
+
+**State-based CRDTs (CvRDTs):**
+- Replicas send full state to peers
+- Merge function computes join of two states
+- Only requires gossip protocol (unreliable transport OK)
+- Higher bandwidth (full state transfer)
+
+**Operation-based CRDTs (CmRDTs):**
+- Replicas send only operations
+- Requires reliable, causal-order delivery
+- Lower bandwidth (just operations)
+- More complex middleware requirements
+
+### Common CRDT Types
+| Type | Description | Use Case |
+|------|-------------|----------|
+| G-Counter | Grow-only counter, per-node counts | View counts, upvotes |
+| PN-Counter | Positive-negative counter | Likes minus dislikes |
+| G-Set | Grow-only set | Tag collections |
+| OR-Set | Observed-remove set (add wins on concurrent add/remove) | Member lists |
+| LWW-Register | Last-writer-wins register | Profile fields |
+| LWW-Map | Map of LWW-Registers | Agent state objects |
+| Sequence/RGA | Replicated growable array | Collaborative editing |
+
+### State Synchronization
+- **State-based:** Periodically gossip full state; merge on receive
+- **Operation-based:** Broadcast operations; apply in causal order
+- **Delta-state CRDTs:** Send only the delta (diff) since last sync — best of both worlds
+- Merge is always safe — applying the same update multiple times has no effect (idempotent)
+
+### Offline/Reconnect Behavior
+- **Perfect offline support** — updates applied locally, merged on reconnect
+- No conflict resolution needed — merge is automatic and deterministic
+- Reconnecting node sends its state/operations; receiving nodes merge
+- Works perfectly with intermittent connectivity
+
+### Tradeoffs
+- (+) No coordination/consensus needed — fully decentralized
+- (+) Perfect offline support
+- (+) Mathematically guaranteed convergence
+- (+) Low latency — local writes, async merge
+- (-) Limited data structure types — not everything can be a CRDT
+- (-) State-based CRDTs can be bandwidth-heavy
+- (-) Metadata overhead (tombstones, vector clocks)
+- (-) Monotonically growing state (hard to garbage collect)
+- (-) "Last writer wins" may not always be the right semantics
+
+### Key Lessons for Agent Mesh
+- **CRDTs are the ideal state synchronization mechanism for agent mesh networks**
+- **Agent state (mood, energy, capabilities) maps naturally to LWW-Registers and OR-Sets**
+- **Delta-state CRDTs** balance bandwidth and consistency — critical for mobile agents
+- **Offline-first by design** — agents can operate independently and merge later
+- **G-Counter pattern** works for agent interaction counts, coupling strength
+- **OR-Set** is perfect for agent peer lists, subscriptions, capability sets
+- **Metadata growth** must be managed — agent state should be prunable
+
+---
+
+## 9. ActivityPub
+
+**What it is:** W3C standard for federated social networking. Powers the Fediverse (Mastodon, Pixelfed, PeerTube, etc.).
+
+### Core Design Principles
+- **Actor model** — every entity (user, group, app) is an Actor with inbox/outbox
+- **ActivityStreams 2.0** vocabulary — standardized JSON-LD for describing activities
+- **Dual API:** Client-to-Server (C2S) for posting, Server-to-Server (S2S) for federation
+- **HTTP-based** — standard web infrastructure
+
+### Discovery Mechanism
+- **WebFinger** — `/.well-known/webfinger?resource=acct:user@domain` resolves actor URL
+- **Actor URLs** are HTTPS endpoints returning JSON-LD actor documents
+- **Followers/following** collections provide social graph discovery
+- No global directory — discovery through social graph traversal
+
+### Transport Model
+- **HTTPS POST** to actor inboxes for delivery
+- **HTTP Signatures** for authentication (proving sender identity)
+- JSON-LD with ActivityStreams 2.0 vocabulary
+- Polling via `outbox` collection for pull-based access
+
+### Message Format
+- JSON-LD wrapping ActivityStreams 2.0
+- Activities: Create, Update, Delete, Follow, Accept, Reject, Like, Announce, etc.
+- Objects: Note, Article, Image, Video, Event, etc.
+- Each actor has: `id` (URL), `inbox`, `outbox`, `followers`, `following`, `publicKey`
+
+### State Synchronization
+- **Push-based:** Activities POSTed to follower inboxes
+- **No global state** — each server maintains its own copy of remote actors/content
+- **No conflict resolution** — activities are append-only
+- **No backfill** — if a server was down when an activity was sent, it may be lost
+
+### Offline/Reconnect Behavior
+- **Server inbox queues** — activities wait in sender's outbox retry queue
+- Delivery retried with exponential backoff (implementation-specific)
+- No guaranteed delivery — retries eventually give up
+- No catch-up mechanism for missed activities during extended outages
+
+### Central vs P2P
+- **Federated** — each instance is a server for its users
+- No central authority, but large instances have outsized influence
+- Server admins control moderation, defederation
+
+### Tradeoffs
+- (+) Uses standard web infrastructure (HTTPS, JSON, DNS)
+- (+) Actor model is intuitive and extensible
+- (+) Large ecosystem (Mastodon, Pixelfed, etc.)
+- (+) ActivityStreams vocabulary is rich and standardized
+- (-) No guaranteed delivery
+- (-) No backfill/catch-up mechanism
+- (-) JSON-LD is complex and often implemented incompletely
+- (-) Instance admins have significant power over users
+- (-) Discovery is slow (requires multiple HTTP requests)
+
+### Key Lessons for Agent Mesh
+- **Actor model with inbox/outbox** is a natural fit for agents
+- **ActivityStreams vocabulary** could be extended for agent activities (Sense, Decide, Act, Couple)
+- **HTTP Signatures** pattern is practical for agent authentication
+- **WebFinger** is an elegant discovery mechanism for named agents
+- **Lack of backfill is a critical gap** — agents need catch-up mechanisms
+- **JSON-LD complexity is a warning** — keep the message format simple
+
+---
+
+## 10. Bluetooth Mesh
+
+**What it is:** Bluetooth SIG standard for many-to-many device communication using BLE advertising. Designed for building automation, lighting, sensor networks.
+
+### Core Design Principles
+- **Managed flooding** — messages broadcast to all nodes, relayed hop-by-hop
+- **Publish/Subscribe** — nodes publish to and subscribe to addresses (topics)
+- **Low power support** — Friend/Low Power Node pattern
+- **Provisioning** — secure device onboarding with network key distribution
+- **No routing tables** — flooding eliminates routing complexity
+
+### Discovery Mechanism
+- **Provisioning:** Unprovisioned devices send beacons; a Provisioner discovers and onboards them
+- **Network keys** define mesh membership — only nodes with the key can participate
+- **Group addresses** for multicast communication
+
+### Transport Model
+- **BLE advertising** as bearer — no connection needed for mesh messages
+- **GATT connections** via Proxy Nodes for non-mesh devices (phones)
+- **Managed flooding** with TTL to limit propagation
+- **Network layer relay** — relay nodes rebroadcast messages
+- **Segmentation** for messages larger than one advertisement
+
+### Message Format
+- Binary, compact format
+- Layers: Bearer → Network (encryption, relay) → Transport (segmentation) → Access (application data) → Model (standardized behaviors)
+- Network PDU: ~29 bytes maximum per advertisement
+- Messages encrypted with network key (network layer) and application key (application layer)
+
+### State Synchronization
+- **Publish/Subscribe model** — state changes published to group addresses
+- **No global state** — each node maintains its own state
+- **Provisioning data** (keys, addresses) distributed during device onboarding
+- **Configuration model** standardizes how nodes are configured
+
+### Offline/Reconnect Behavior
+- **Friend Node pattern:** A mains-powered Friend Node stores messages for associated Low Power Nodes (LPNs)
+- LPN wakes periodically, polls Friend Node, receives queued messages
+- LPN can sleep for hours/days — Friend stores messages until polled
+- **No replay protection for sleeping nodes** — relies on sequence numbers
+
+### Central vs P2P
+- **Fully P2P** in message transport (flooding)
+- **Provisioner** is a semi-central role for onboarding
+- No routing infrastructure — any relay node forwards any message
+
+### Tradeoffs
+- (+) No routing tables — extreme simplicity
+- (+) Friend/LPN pattern brilliantly solves low-power problem
+- (+) Managed flooding is robust to topology changes
+- (+) Double encryption (network + application layer)
+- (+) Provisioning provides secure onboarding
+- (-) Flooding doesn't scale — limited to ~hundreds of nodes
+- (-) Bandwidth limited (BLE advertising)
+- (-) No acknowledgment at mesh layer
+- (-) Latency increases with network size
+- (-) TTL must be tuned carefully
+
+### Key Lessons for Agent Mesh
+- **Friend/LPN pattern** is directly applicable — a cloud relay stores messages for sleeping mobile agents
+- **Managed flooding with TTL** works for small agent clusters
+- **Provisioning model** is relevant for agent onboarding (key exchange, capability declaration)
+- **Publish/Subscribe with group addresses** maps to agent topic subscriptions
+- **Flooding won't scale** — need structured routing for large agent networks
+- **Double encryption model** (transport + application) provides defense in depth
+
+---
+
+## Mobile P2P: Background Restrictions and Patterns
+
+### iOS Restrictions
+- **Multipeer Connectivity:** Only works in foreground; networking stops within ~3 minutes of backgrounding
+- **BLE scanning in background:** Reduced frequency; `AllowDuplicates` option ignored; only one advertisement received
+- **BLE advertising in background:** Severely throttled; Apple limits frequency and eventually cuts off
+- **No background TCP/UDP sockets** — suspended apps lose all connections
+- **Background App Refresh:** Limited, unpredictable scheduling by OS
+- **Push Notifications (APNs):** Only reliable way to wake an app — but limited to triggering brief background execution (~30 seconds)
+- **Background Processing Tasks (BGTaskScheduler):** Can run for minutes, but OS controls scheduling
+
+### Android Restrictions
+- **Doze Mode:** Network access suspended; alarms deferred; wake locks ignored
+- **`setAndAllowWhileIdle()`:** Can fire alarms in Doze, but max once per 9 minutes per app
+- **Foreground Services:** Keep app alive but require persistent notification; battery drain
+- **Background Services:** Killed by OS in recent Android versions
+- **Firebase Cloud Messaging (FCM):** Reliable wake mechanism (equivalent to APNs)
+
+### Patterns for Waking Sleeping Mobile Nodes
+
+1. **Push Notification Relay:** Central server sends push notification (APNs/FCM) to wake agent, agent connects to relay, receives pending messages, processes, goes back to sleep
+2. **Friend Node Pattern (from Bluetooth Mesh):** A cloud-based "friend" stores messages for sleeping agents; agent polls when it wakes
+3. **Scheduled Background Tasks:** Agent requests periodic wake-ups via `BGTaskScheduler` (iOS) or `WorkManager` (Android); unpredictable timing but no server needed
+4. **BLE Peripheral Mode:** Agent advertises as BLE peripheral; can receive connections even when backgrounded (iOS allows this with `bluetooth-peripheral` background mode)
+5. **VoIP Push (iOS):** `PushKit` provides high-priority push that wakes app instantly — but Apple rejects apps that misuse this for non-VoIP purposes
+6. **Foreground Service (Android):** Keeps agent fully alive at cost of persistent notification and battery drain
+
+### Recommended Architecture for Mobile Agents
+The most practical pattern combines:
+- **Cloud relay** (like MQTT broker or Matrix homeserver) as persistent message store
+- **Push notifications** (APNs/FCM) to wake agents when messages arrive
+- **Brief wake processing** — agent connects to relay, syncs state, processes messages, returns to sleep
+- **CRDTs** for state sync — agents merge state on each wake cycle, no coordination needed
+
+---
+
+## Mesh Networks and Intermittent Connectivity
+
+### Delay-Tolerant Networking (DTN)
+- **Core insight:** Treat disconnection as the norm, not the exception
+- **Bundle Protocol (BP):** Messages ("bundles") are self-contained units with addressing, TTL, and custody transfer
+- **Store-Carry-Forward:** Nodes store bundles, physically carry them (mobile nodes), and forward when connectivity available
+- **Custody Transfer:** Responsibility for delivery can be handed off between nodes
+- **Frame Sequence Numbers:** Each producer assigns monotonic sequence numbers; consumers request missing sequences on reconnect
+- **NASA uses DTN** for deep-space communication (minutes/hours of delay)
+
+### Patterns for Intermittent Connectivity
+
+1. **Sequence Numbers + Gap Detection:** Each producer maintains monotonic sequence (FSEQ). Consumers track last received FSEQ. On reconnect, request missing range. Simple and effective.
+
+2. **Vector Clocks / Version Vectors:** Each node maintains a vector of counters (one per known node). On sync, compare vectors to determine what's missing. More complex but handles multi-source updates.
+
+3. **Merkle Trees / Hash-Based Sync:** Compare root hash to detect divergence. Walk tree to find specific differences. Efficient for large state with small changes (used by Git, Cassandra).
+
+4. **CRDTs + Gossip:** Combine CRDTs for conflict-free merge with gossip for opportunistic sync. Each connection is an opportunity to merge state. Perfect for intermittent connectivity.
+
+5. **Log-Based Sync (Event Sourcing):** Append-only log of events. Each event has globally unique ID. On reconnect, exchange events not seen by the other. Matrix's event DAG is a variant.
+
+---
+
+## Summary: Patterns and Principles for AI Agent Mesh Protocol
+
+### Architecture Patterns
+
+| Pattern | Source Protocols | Applicability to Agent Mesh |
+|---------|-----------------|---------------------------|
+| **Keypair Identity** | Nostr, libp2p | Agent identity = cryptographic keypair. No registration needed. |
+| **Relay/Friend Node** | Nostr, MQTT, BT Mesh | Cloud relay stores messages for sleeping/offline agents. Essential for mobile. |
+| **Pub/Sub with Topics** | MQTT, GossipSub, BT Mesh | Agents subscribe to capability/mood/context topics. Natural routing. |
+| **Event DAG** | Matrix | Ordered, immutable record of agent interactions. Supports backfill. |
+| **Actor Model (Inbox/Outbox)** | ActivityPub | Each agent has inbox (receives) and outbox (publishes). Clean abstraction. |
+| **Managed Flooding + TTL** | BT Mesh, Gossip | Works for small clusters. TTL prevents infinite propagation. |
+| **Structured Routing (DHT)** | Kademlia | O(log n) discovery for large networks. Not real-time. |
+| **Dual View (Active + Passive)** | HyParView | Active peers for communication, passive for fault tolerance. |
+| **Piggyback Dissemination** | SWIM | Reuse existing messages to propagate membership/state changes. Zero extra cost. |
+
+### State Synchronization Strategy
+
+**Recommended: Delta-state CRDTs + Gossip + Event Log**
+
+1. **Agent state** (mood, energy, capabilities, coupling weights) → **LWW-Map CRDT**
+   - Each agent maintains its own state as a CRDT
+   - On any connection, agents merge state — order doesn't matter, always converges
+   - Delta-state variant minimizes bandwidth
+
+2. **Agent peer sets** (who I'm coupled with) → **OR-Set CRDT**
+   - Add/remove peers without coordination
+   - Concurrent add+remove → add wins (safe default)
+
+3. **Interaction history** → **Append-only event log with sequence numbers**
+   - Each agent maintains monotonic sequence number
+   - On reconnect, request missing events by sequence range
+   - Events are immutable and signed
+
+4. **Coupling strength** → **Bounded Counter CRDT**
+   - Decays over time (agent applies local decay function)
+   - Incremented by interactions
+   - Merge takes maximum of decayed values
+
+### Discovery Strategy
+
+**Recommended: Layered Discovery**
+
+1. **Bootstrap:** Known relay servers (like MQTT brokers or Nostr relays)
+2. **Local:** mDNS / BLE for same-network agent discovery
+3. **Global:** DHT for finding agents by capability/ID
+4. **Social:** Agent publishes relay list (Nostr NIP-65 pattern); other agents find you through your relays
+5. **Push:** APNs/FCM to wake sleeping mobile agents
+
+### Message Routing Strategy
+
+**Recommended: Hybrid Pub/Sub + Direct**
+
+1. **Topic-based pub/sub** for broadcast (mood changes, capability announcements)
+   - Via relay servers (MQTT/Nostr pattern)
+   - Topics map to agent contexts: `mood/#`, `capability/#`, `mesh/coupling/#`
+
+2. **Direct messaging** for agent-to-agent coupling
+   - Via relay (store-and-forward for offline agents)
+   - Via direct connection (WebRTC DataChannel for real-time, low-latency)
+
+3. **Gossip** for metadata propagation
+   - SWIM-style piggyback on existing messages
+   - Membership changes, capability updates, health signals
+
+### Offline/Reconnect Strategy
+
+**Recommended: Store-Forward-Merge**
+
+1. **Relay stores messages** while agent is offline (MQTT persistent session pattern)
+2. **Push notification wakes agent** when priority message arrives (APNs/FCM)
+3. **Agent connects to relay, pulls pending messages** (Nostr REQ pattern)
+4. **Agent merges state with CRDT** — automatic, conflict-free convergence
+5. **Agent publishes its updated state** — peers merge on their next sync
+6. **Sequence numbers enable gap detection** — agent requests missing events (DTN pattern)
+
+### Mobile-Specific Design Principles
+
+1. **Assume agents are usually asleep** — design for intermittent connectivity as the norm
+2. **Cloud relay is not optional** — iOS/Android kill background networking; relay is the Friend Node
+3. **Push notifications are the only reliable wake mechanism** on mobile
+4. **Minimize wake processing** — connect, sync CRDTs, process priority messages, sleep
+5. **BLE for proximity** — when agents are physically nearby, BLE works even in background (iOS)
+6. **Battery budget is the primary constraint** — every design choice must consider power
+
+### Protocol Design Recommendations
+
+1. **Keep it Nostr-simple:** Keypair identity, JSON events, WebSocket transport, relay architecture
+2. **Add MQTT's QoS:** Support fire-and-forget (QoS 0) and guaranteed delivery (QoS 1)
+3. **Use CRDTs for state:** Agent state is a delta-state CRDT — merge on every sync
+4. **Adopt SWIM's piggyback:** Propagate mesh metadata on existing messages for free
+5. **Support Matrix-style backfill:** Agents can request historical events by sequence range
+6. **Design for the Friend Node pattern:** Relay stores messages for sleeping agents, delivers on poll
+7. **Layer discovery:** mDNS (local) → relay (cloud) → DHT (global) → push (wake)
+8. **Event-based, not request-response:** All communication is signed, immutable events with kinds
+9. **Coupling as first-class concept:** Unlike any existing protocol, agent coupling strength should be a protocol-level concept encoded in CRDTs
+10. **Autonomous, not automated:** Agents decide whether to respond to events based on their coupling engine — the protocol transports, it doesn't mandate behavior
+
+### What No Existing Protocol Provides
+
+None of the surveyed protocols address these agent-specific requirements:
+
+- **Coupling dynamics** — weighted, decaying relationships between peers that influence routing
+- **Mood/state-aware routing** — message priority and routing based on agent emotional/energy state
+- **Autonomous response decisions** — protocol-level support for agents choosing whether to act
+- **Context-aware presence** — richer than online/offline; includes mood, energy, attention, coupling strength
+- **Collective state emergence** — mesh-level state that emerges from individual agent states
+
+These gaps define the unique value proposition of a purpose-built agent mesh protocol.
+
+---
+
+## Sources
+
+### libp2p
+- [libp2p Official Site](https://libp2p.io/)
+- [libp2p Architecture Spec](https://github.com/libp2p/specs/blob/master/_archive/4-architecture.md)
+- [libp2p Peers Documentation](https://docs.libp2p.io/concepts/fundamentals/peers/)
+- [GossipSub Spec](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.0.md)
+
+### Matrix
+- [Matrix Specification](https://spec.matrix.org/latest/)
+- [Matrix Protocol Wikipedia](https://en.wikipedia.org/wiki/Matrix_(protocol))
+- [Matrix.org](https://matrix.org/)
+- [Matrix Protocol Comprehensive Study](https://link.springer.com/article/10.1186/s13677-025-00829-7)
+
+### Nostr
+- [Nostr Protocol](https://nostr.com/)
+- [NIP-01 Basic Protocol](https://nips.nostr.com/1)
+- [Nostr GitHub](https://github.com/nostr-protocol/nostr)
+- [How Nostr Works](https://nostr.how/en/the-protocol)
+
+### MQTT
+- [MQTT.org](https://mqtt.org/)
+- [HiveMQ MQTT Essentials](https://www.hivemq.com/mqtt/)
+- [MQTT Pub/Sub Architecture](https://www.hivemq.com/blog/mqtt-essentials-part2-publish-subscribe/)
+- [EMQ MQTT Guide](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-mqtt)
+
+### WebRTC
+- [WebRTC Protocols - MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols)
+- [WebRTC Getting Started](https://webrtc.org/getting-started/peer-connections)
+- [WebRTC for the Curious](https://webrtcforthecurious.com/docs/01-what-why-and-how/)
+
+### Kademlia
+- [Kademlia Guide - Stanford](https://codethechange.stanford.edu/guides/guide_kademlia.html)
+- [IPFS DHT Docs](https://docs.ipfs.tech/concepts/dht/)
+- [Kademlia Wikipedia](https://en.wikipedia.org/wiki/Kademlia)
+
+### Gossip Protocols
+- [SWIM Protocol Explained](https://www.brianstorti.com/swim/)
+- [SWIM Paper (Cornell)](https://www.cs.cornell.edu/projects/Quicksilver/public_pdfs/SWIM.pdf)
+- [HyParView Paper](https://asc.di.fct.unl.pt/~jleitao/pdf/dsn07-leitao.pdf)
+
+### CRDTs
+- [CRDT.tech](https://crdt.tech/)
+- [CRDT Dictionary](https://www.iankduncan.com/engineering/2025-11-27-crdt-dictionary/)
+- [CRDTs - Redis](https://redis.io/blog/diving-into-crdts/)
+- [CRDTs - Ably](https://ably.com/blog/crdts-distributed-data-consistency-challenges)
+
+### ActivityPub
+- [W3C ActivityPub Spec](https://www.w3.org/TR/activitypub/)
+- [ActivityPub Rocks](https://activitypub.rocks/)
+- [ActivityPub Wikipedia](https://en.wikipedia.org/wiki/ActivityPub)
+
+### Bluetooth Mesh
+- [Bluetooth Mesh FAQ](https://www.bluetooth.com/learn-about-bluetooth/feature-enhancements/mesh/mesh-faq/)
+- [Bluetooth Mesh Guide](https://novelbits.io/bluetooth-mesh-networking-the-ultimate-guide/)
+- [Bluetooth Mesh Directed Forwarding](https://www.bluetooth.com/mesh-directed-forwarding/)
+
+### Mobile P2P
+- [iOS Core Bluetooth Background Processing](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html)
+- [Apple Multipeer Connectivity](https://developer.apple.com/documentation/multipeerconnectivity)
+- [iOS P2P Exploration - Thali Project](http://thaliproject.org/iOSp2p/)
+
+### Delay-Tolerant Networking
+- [Z-Mesh DTN Overview](https://z-mesh.org/overviews/delay-tolerant.html)
+- [NASA DTN Tutorial](https://www.nasa.gov/wp-content/uploads/2023/09/dtn-tutorial-v3.2-0.pdf)
+- [DTN Wikipedia](https://en.wikipedia.org/wiki/Delay-tolerant_networking)