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.

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

@@ -0,0 +1,105 @@
+# OpenSpec Change: network-transport-gundb
+
+- **Change ID**: network-transport-gundb
+- **Package**: `@suaveplan/network-transport-gundb`
+- **Category**: browser
+- **Target path**: `packages/network/network-transport-gundb`
+- **Status**: PROPOSED (architecture decision required at implementation time — see §"Split vs. fold")
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 3
+- **Sibling**: `network-discovery-gundb` (Wave 2)
+- **Supersedes**: the original name reservation in this folder (2026-05-11)
+
+---
+
+## Summary
+
+Reserve and define migration scope for `@suaveplan/network-transport-gundb` — a browser-tier `Transport` implementation over GunDB gossip-over-WebSocket. Wraps the connection-management subsystem of `network-discovery-gundb` (Wave 2) into a standalone `Transport` that registers with `@suaveplan/network-plugin-transport-manager` ✅.
+
+---
+
+## Split vs. fold — architecture decision required
+
+Upstream (`../suaveplan/packages/browser/network-discovery-gundb/`) bundles **discovery + transport** in a single package: upstream `GunDBDiscovery` (244 LOC) + `gun-node-manager` (211 LOC) bundle gossip rendezvous with the underlying Gun node lifecycle. Two implementation paths are valid; the migrating engineer chooses based on the audit:
+
+### Option A — Split (recommended for new code)
+
+Two genesis packages:
+
+1. `network-discovery-gundb` — pure `DiscoveryStrategy` producing peer endpoints
+2. `network-transport-gundb` — pure `Transport` implementation over GunDB gossip-over-WebSocket
+
+Pro: cleaner separation, transport-manager can pick this transport without inheriting the discovery package. Matches the family-naming convention.
+
+Con: more genesis packages, more boundaries to maintain, divergence from upstream layout.
+
+### Option B — Fold
+
+Single genesis package: `network-discovery-gundb` ships both `DiscoveryStrategy` AND a `Transport` adapter. `network-transport-gundb` becomes a thin re-export of the transport surface only.
+
+Pro: parity with upstream layout, fewer moving parts.
+
+Con: anyone importing `network-transport-gundb` drags in the discovery dep.
+
+**Decision deferred** to the implementing proposal. This proposal reserves the name + path under both options.
+
+---
+
+## Current-state audit
+
+See parallel proposal `openspec/changes/network-discovery-gundb/proposal.md` for the full upstream surface inventory (it covers both the discovery and transport subsystems).
+
+Transport-specific subsystem (extracted from the bundled upstream package):
+
+- Per-peer connection wrapper
+- Connection lifecycle (open / close / heartbeat / cleanup)
+- Wire-format encoding/decoding over GunDB gossip-over-WebSocket
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| Per-peer connection wrapper | ✅ | ✅ | |
+| `Transport` contract impl | partial (embedded in discovery class) | ⬆️ | NEW `Transport` adapter or extracted from bundled code per Option A/B. |
+| `NetworkPlugin` wrapper | partial | ⬆️ | Mirrors `WebRTCPlugin` shape. |
+| Wire-format framing over GunDB gossip-over-WebSocket | ✅ | ✅ | Re-use `@suaveplan/serialize` length-prefix where applicable. |
+| Structured errors | 🚫 | ⬆️ | Strategy-specific code registry. |
+| Zod boundary validation | 🚫 | ⬆️ | Every public option struct. |
+| OTel instrumentation | 🚫 | ⬆️ | Spans + counters + histograms. |
+| AbortSignal | 🚫 | ⬆️ | Threaded everywhere. |
+| Insecure default rejection | inherited from `network-discovery-gundb` | ⬆️ | Same — no public-relay/tracker/broker fallbacks. |
+| Test-runner imports | direct vitest | ⬆️ | `@suaveplan/testing/runner` per §7. |
+| 100% test coverage | 🚫 | ⬆️ | Bring to 100/100/100/100. |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/network` ✅
+- `@suaveplan/network-plugin-transport-manager` ✅
+- `@suaveplan/network-transport-webrtc` ✅ (composes `RTCPeerConnection` where applicable)
+- `network-discovery-gundb` ⬅ Wave 2 (sibling — required if Option B, optional peer-dep if Option A)
+- `@suaveplan/types`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/timing`, `@suaveplan/retry` ✅
+- `@suaveplan/testing` ✅
+- External: `gun`.
+
+**Blocking note.** `network-discovery-gundb` (Wave 2) must land first regardless of Option A/B — Option A pairs with it, Option B is implemented inside it.
+
+---
+
+## Acceptance gate
+
+1. `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-gundb` green.
+2. `bunx turbo test:coverage --filter=@suaveplan/network-transport-gundb` 100/100/100/100.
+3. `bun run docs:check` green.
+4. Integration test with `network-plugin-transport-manager`: register this transport, send envelope through it, verify peer receives.
+5. `STATUS.md` row flipped from `–` to `✅`.
+
+---
+
+## Out of scope
+
+- Hosting / running any required relays, trackers, or brokers (deployment concern).
+- Cross-transport peer migration (covered by transport-manager + standby).

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

@@ -0,0 +1,59 @@
+# Tasks — network-transport-gundb
+
+## Phase 0: Decide split vs. fold
+
+- [ ] 0.1 Read `network-discovery-gundb` source after its Wave-2 migration ships. Decide Option A (split) or Option B (fold) per the parent proposal §"Split vs. fold".
+- [ ] 0.2 Record decision in this tasks.md (replace this section with the chosen path).
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-transport-gundb/` (Option A) OR add `./transport` subpath to `network-discovery-gundb` (Option B).
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`.
+- [ ] 1.3 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
+
+## Phase 2: Transport impl
+
+- [ ] 2.1 Extract / author per-peer connection wrapper.
+- [ ] 2.2 Author `Transport` adapter (`connect`/`disconnect`/`send`/`onMessage`/`getConnectedPeers`/`close`).
+- [ ] 2.3 Author `NetworkPlugin` wrapper mirroring `WebRTCPlugin`.
+- [ ] 2.4 Sibling `.md` per impl file.
+- [ ] 2.5 Conformance tests for `Transport` + `NetworkPlugin` contracts.
+
+## Phase 3: Types + errors
+
+- [ ] 3.1 Public transport types into `src/types/` + sibling `.md`.
+- [ ] 3.2 `defineCodes` registry with transport-specific failure codes.
+- [ ] 3.3 Zod schemas for every public option struct.
+
+## Phase 4: Observability
+
+- [ ] 4.1 Spans for connect/disconnect/send.
+- [ ] 4.2 Counters `<transport>.peers_connected{outcome}`, `<transport>.messages_total{direction,outcome}`.
+- [ ] 4.3 Gauge `<transport>.active_peers`.
+
+## Phase 5: Integration
+
+- [ ] 5.1 Register with `network-plugin-transport-manager` test harness.
+- [ ] 5.2 Verify multi-transport scenario: register WebRTC + this transport, observe priority routing.
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests where applicable.
+- [ ] 6.3 100/100/100/100 coverage gate.
+- [ ] 6.4 Root `README.md` documenting Option A vs. B choice + usage.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-gundb` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-transport-gundb` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — Option A/B decision recorded.
+- [ ] Row 3 — Manager integration test passes.
+- [ ] Row 4 — Folder archived.