Initial Commit

openspec/archive/2026-05-12-network-transport-gundb/DECISION.md

@@ -0,0 +1,25 @@
+# Decision: FOLD into `network-discovery-gundb` (not split)
+
+- **Date**: 2026-05-12
+- **Decided by**: autonomous Wave 3.5 implementation
+- **Parent**: `network-transport-family` proposal, §"Split vs. fold" for discovery-bundled transports
+
+## Outcome
+
+`@suaveplan/network-transport-gundb` is NOT shipped as a separate package. Its functionality lives at `@suaveplan/network-discovery-gundb/transport` (subpath export of the existing discovery package).
+
+## Rationale
+
+1. Upstream code bundles transport + discovery as one integrated unit; the existing gossip rendezvous already moves messages between peers — the transport adapter exposes that as a `Transport` contract.
+2. **Security uplift sharing**: Folding lets the transport adapter reuse the existing `signEnvelope` / `verifyEnvelopeSignature` path AND the same defensive inbound handler that silently drops unsigned/tampered/malformed messages. Every `transport.send()` flows through `signEnvelope` (Ed25519 over canonical bytes); every inbound payload is Zod-parsed → verified → senderPeerId-matched → recipient-matched BEFORE any caller handler is invoked. Splitting would risk the transport bypassing this defensive layer.
+3. Same `gundb.invalid_messages_total{reason}` and `gundb.signature_rejected_total{reason}` security counters cover both tiers.
+
+## What to import
+
+- Discovery: `import { GunDBDiscovery } from "@suaveplan/network-discovery-gundb"`
+- Transport: `import { GunDBTransport, GunDBPlugin } from "@suaveplan/network-discovery-gundb/transport"` (or `/plugin`)
+- Envelope signing: imported via the transport package; the existing `./signing` subpath for discovery announces stays unchanged.
+
+## Security guarantee
+
+Tests explicitly verify that unsigned envelopes, single-bit-flipped signatures, mismatched senderPeerId, wrong recipientPeerId, and malformed wire payloads are ALL dropped at the receiver without invoking the caller handler. The transport adapter is a facade, not a bypass.