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

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.