first commit

2026-07-30 23:02:00 -04:00
commit fd537ed47e
48 changed files with 3059 additions and 0 deletions
@@ -0,0 +1,38 @@
+# ADR-0006: Private world transport via HyperDHT TCP tunnel
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+Guests must reach a host Squid without public port forwards. Holesail implements this pattern but is **AGPL-3.0**. Re-encoding the full Minecraft protocol over Protomux is version-fragile.
+
+## Decision
+
+Implement an **in-house Apache-2.0 HyperDHT byte pipe**:
+
+- Host: `dht.createServer` + pipe each connection to `127.0.0.1:squidPort`
+- Guest: local loopback accept + `dht.connect(worldKey)` + pipe
+- Opaque TCP bytes (no MC packet parse on the tunnel)
+
+Do **not** hard-depend on `holesail`.
+
+Optional: capability proof on stream open (`hyperswarm-capability`).
+
+## Consequences
+
+### Positive
+
+- Works for any Squid-supported protocol version
+- License-safe
+- Matches peardock “data plane” concept without AGPL
+
+### Negative / tradeoffs
+
+- One pipe per client connection (resource management needed)
+- Latency = P2P RTT (not LAN)
+
+### Follow-ups
+
+- [ ] Phase 2 `lib/world-tunnel`
+- [ ] Concurrency limits and backpressure