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

OpenSpec Change: network-transport-family

• Change ID: network-transport-family
• Type: naming convention + restructure
• Status: PROPOSED
• Date: 2026-05-11
• Related: network-suite (2026-04-29), enterprise-network-rename (2026-05-01)

---

Summary

Introduce a dedicated @suaveplan/network-transport-* package family for concrete Transport implementations consumed by @suaveplan/network-plugin-transport-manager. Reclassifies one shipped plugin, retires one pre-OpenSpec orphan, and net-adds seven transport packages currently listed under – (unmigrated) in STATUS.md. Reserves network-plugin-* for cross-cutting orchestration plugins (governance, failover, qos, audit-mesh, …) and reserves network-discovery-* for peer rendezvous strategies.

This is a naming + boundary change. No new transport functionality is implemented in this proposal — each concrete transport gets its own follow-up migration change with the standard parity checklist.

---

Why

Today the @suaveplan/network-plugin-* namespace conflates two categorically different things:

1. Wire-level Transport implementations — webrtc, websockets, hyperswarm, libp2p, trystero, gundb, peerjs, webtorrent. These all implement the same structural Transport contract (connect/disconnect/send/onMessage/onPeerEvent/getConnectedPeers/close) defined in @suaveplan/network and are orchestrated as a pool by network-plugin-transport-manager ✅.
2. Cross-cutting orchestration plugins — governance, failover, qos, partition, circuit-breaker, audit-mesh, server-bridge, content-delivery, migration, auth, crypto-messages, state, relay, assignment, protocol, registry, session, topology, monitor, simulation, intra-relay, devtools, middleware. These hook into the NetworkPlugin lifecycle but do not move bytes on the wire.

Collapsing both into network-plugin-* hides this distinction. The package list (35 plugins per MANIFEST.md) is impossible to scan for "what transports exist?" without inspecting each package.json. Discovery tooling, transport-manager configuration, and downstream documentation all suffer.

Three further problems:

• Drive already follows this convention. @suaveplan/drive-transport-https ✅ ships today. The network side should match.
• The – backlog is full of unnamed transports. STATUS.md lists network-hyperswarm, network-libp2p, network-libp2p-server, network-standby-transport, network-webrtc, network-websockets as pending. Half of these are transports, half are something else; the bare names give no clue.
• Pre-OpenSpec orphans pollute the namespace. @suaveplan/network-{topology,failover,governance} shipped before OpenSpec was set up properly in genesis and were already superseded by their network-plugin-* counterparts. (Deleted on this branch — see §3.)

A first-class network-transport-* family solves all three: clear contract boundary, scannable inventory, parallel with drive-transport-* / network-discovery-*, and a natural home for the pending wire-level packages.

---

What changes

1. Renames (shipped → renamed)

Before	After	Reason
@suaveplan/network-plugin-webrtc ✅	@suaveplan/network-transport-webrtc	Concrete Transport impl, not an orchestration plugin.

Path move: packages/network/network-plugin-webrtc/ → packages/network/network-transport-webrtc/.

The package continues to expose a NetworkPlugin wrapper for backward compatibility — the NetworkPlugin interface is how transports register with NetworkNode. The rename clarifies role, not contract.

2. Promotions (bare → transport)

Before	After	Reason
@suaveplan/network-websockets ✅ (bare, pre-OpenSpec)	@suaveplan/network-transport-websockets	Pre-OpenSpec migration; folds into the transport family with proper plugin wrapper.

Path move: packages/network/network-websockets/ → packages/network/network-transport-websockets/.

3. Already-deleted orphans (no action — recorded for traceability)

These three packages were migrated from suaveplan before OpenSpec was set up properly in this monorepo and were never referenced by any consumer. They were deleted on the genesis branch on 2026-05-11. Their canonical network-plugin-* replacements are already shipped.

Deleted	Canonical replacement
@suaveplan/network-topology (no consumers)	@suaveplan/network-plugin-topology ✅
@suaveplan/network-failover (no consumers)	@suaveplan/network-plugin-failover ✅
@suaveplan/network-governance (no consumers)	@suaveplan/network-plugin-governance ✅

4. New transport packages (status – → scoped, implementation deferred)

Each of these gets a stub package.json at 0.1.0, an openspec/changes/network-transport-<name>/proposal.md with the standard migration parity checklist (per AGENTS.md §0a), and a tasks.md. Implementation is out of scope for this proposal — this change only reserves names + paths + spec slots.

Package	Source mapping	Tier
@suaveplan/network-transport-hyperswarm	../suaveplan/enterprise/network-hyperswarm.md	server (Node-only)
@suaveplan/network-transport-libp2p	../suaveplan/enterprise/network-libp2p.md	universal
@suaveplan/network-transport-trystero	../suaveplan/enterprise/network-trystero*.md	browser
@suaveplan/network-transport-gundb	../suaveplan/enterprise/network-gundb*.md	universal
@suaveplan/network-transport-peerjs	../suaveplan/enterprise/network-peerjs.md (if present)	browser
@suaveplan/network-transport-webtorrent	../suaveplan/enterprise/network-webtorrent.md (if present)	browser
@suaveplan/network-transport-standby	../suaveplan/enterprise/network-standby-transport.md	universal

5. Drive transport — left in place

@suaveplan/drive-transport-https stays where it is. The transport contract there is TransportLike<MessageEnvelope> over a drive-mesh wire, not the Transport contract from @suaveplan/network. Confusable name, different interface. A future change MAY revisit, but this proposal does not touch it.

6. Reserved namespaces (going forward)

Prefix	Contract
@suaveplan/network-transport-*	Implements Transport from @suaveplan/network. Wire-level. Registers with network-plugin-transport-manager.
@suaveplan/network-plugin-*	Implements NetworkPlugin from @suaveplan/network. Cross-cutting orchestration.
@suaveplan/network-discovery-*	Implements peer-rendezvous strategy. Feeds peer identities into transports.
@suaveplan/network-* (bare)	Reserved for @suaveplan/network core + first-class utilities (network-testing ✅). Avoid for new packages — pick one of the three families above.

---

Parity Checklist

Not applicable. This is a naming + restructure change against genesis-shipped code, not a migration from upstream. The per-transport migrations in §4 each carry their own parity checklist when their proposals land.

---

Consumer impact

@suaveplan/network-plugin-webrtc rename

• package.json name change is a breaking import for any consumer importing from @suaveplan/network-plugin-webrtc. Search across genesis:
  • packages/network/network-plugin-transport-manager/ references via workspace:^ — must update.
  • STATUS.md, MANIFEST.md, SUMMARY.md, docs/network/* — regen.
  • openspec/specs/network-webrtc/ — fold delta and rename spec subject if the spec name is package-bound.
• No external (npm) consumers yet — all @suaveplan/network-* packages are at 0.1.0, so the rename has zero release-side cost.

@suaveplan/network-websockets promotion

• Same scope as above. No external consumers; rename in place; regen manifests.

Backward compatibility

• No deprecation shims are required because every @suaveplan/network-* package is still pre-1.0 (0.1.0). Per CLAUDE.md "Package Lifecycle": versions only bump at 1.0 graduation. No deprecation alias packages will be published.

---

Verification approach

The change is complete when:

1. packages/network/network-transport-webrtc/ exists; old path absent.
2. packages/network/network-transport-websockets/ exists; old path absent.
3. Every internal workspace:^ reference to the two renamed packages is updated.
4. bunx turbo lint typecheck test --filter='@suaveplan/network*' is green.
5. bunx turbo test:coverage --filter='@suaveplan/network*' remains at the pre-rename coverage baseline (no test regressions from the path move).
6. bun scripts/folder-reorg/generate-manifest.ts regenerates MANIFEST.md cleanly.
7. STATUS.md, SUMMARY.md, CLAUDE.md package listings reflect the new names.
8. Per-transport child proposals in §4 each exist with proposal.md + tasks.md (implementation deferred).
9. openspec/specs/network-webrtc/ spec is renamed/refolded to match the new package name.
10. Root bun run gate is green.

---

Source mapping

This change has no upstream source — it consolidates a naming convention against genesis shipped code. The per-transport child changes (§4) each map to upstream ../suaveplan/enterprise/network-*.md audit documents.