first commit

agent/ADRs/0003-choose-holepunch-p2p-stack.md

@@ -0,0 +1,43 @@
+# ADR-0003: Choose Holepunch P2P stack
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+Connectivity must be pure peer-to-peer with E2E encryption, topic discovery, multi-writer metadata, and multiplexed app protocols — without app-operated servers.
+
+## Decision
+
+Adopt the Holepunch stack:
+
+| Layer | Packages |
+|-------|----------|
+| Discovery / links | `hyperswarm`, `hyperdht` |
+| Streams | `@hyperswarm/secret-stream` (via swarm) |
+| Multiplex / RPC | `protomux`, `protomux-rpc` |
+| Codecs | `compact-encoding`, `hyperschema` |
+| Storage | `corestore`, `hypercore`, `hyperbee`, `hyperdrive` |
+| Multi-writer | `autobase` (mesh registry) |
+| Capabilities | `hyperswarm-capability` |
+| App shell | `pear-runtime`, `pear-electron` |
+
+Versions pinned from local mirror investigation (see `developer_docs/MODULES.md`).
+
+## Consequences
+
+### Positive
+
+- Battle-tested mesh primitives
+- Matches peardock/hello-pear patterns already used by the team
+- Encryption and holepunching “for free”
+
+### Negative / tradeoffs
+
+- Learning curve for Autobase writer admission
+- DHT bootstrap nodes are third-party infrastructure (acceptable; not app masters)
+
+### Follow-ups
+
+- [ ] Wire worker swarm in Phase 2+
+- [ ] Schema freeze for invites/channels