OpenSpec Change: network-suite

Change ID: network-suite
Packages: Multiple (see below)
Status: PROPOSED
Type: migration-suite
Date: 2026-04-29

Why

The suaveplan monorepo (../suaveplan/) contains a mature network orchestration layer with tiered host nomination, failover, governance elections, compact binary registry, and WebRTC mesh transport. The genesis monorepo has production-grade crypto, streams, storage, events, FSM, and retry primitives that are superior to the suaveplan stubs. This suite migrates the orchestration layer into genesis, reusing genesis primitives instead of porting stubs.

Child changes

Change ID	Package	Status	Description
`network-core`	`@suaveplan/network` (new)	PROPOSED	Core interfaces: `NetworkNode`, `NetworkBus`, `NetworkPlugin`, `Transport`
`network-plugin-webrtc`	`@suaveplan/network-plugin-webrtc` (new)	PROPOSED	WebRTC transport, signaling, mesh, ping/latency
`network-plugin-governance`	`@suaveplan/network-plugin-governance` (new)	PROPOSED	Elections, candidate scoring, voting, transitions, reputation
`network-plugin-failover`	`@suaveplan/network-plugin-failover` (new)	PROPOSED	Heartbeat, health monitor, failover coordinator
`network-plugin-registry`	`@suaveplan/network-plugin-registry` (new)	PROPOSED	Fixed-capacity registry, binary message encoder
`network-plugin-topology`	`@suaveplan/network-plugin-topology` (new)	PROPOSED	Tiered hierarchy, latency groups, group manager
`network-plugin-protocol`	`@suaveplan/network-plugin-protocol` (new)	PROPOSED	13-byte binary header, message encoder/decoder, pipeline
`network-plugin-session`	`@suaveplan/network-plugin-session` (new)	PROPOSED	Logical sessions, nested hierarchies, session-scoped routing, per-session hosts
`network-plugin-transport-manager`	`@suaveplan/network-plugin-transport-manager` (new)	PROPOSED	Multi-transport orchestration, priority routing, round-robin, capability negotiation
`network-plugin-crypto-messages`	`@suaveplan/network-plugin-crypto-messages` (new)	PROPOSED	Ed25519 message signatures, server-signed session/mesh tokens, peer identity verification
`network-plugin-server-bridge`	`@suaveplan/network-plugin-server-bridge` (new)	PROPOSED	WebSocket gateway to central server, offline resilience, log replay, reconciliation
`network-plugin-content-delivery`	`@suaveplan/network-plugin-content-delivery` (new)	PROPOSED	P2P file chunk distribution via mesh, redundancy, integrity, prefetch
`network-plugin-audit-mesh`	`@suaveplan/network-plugin-audit-mesh` (new)	PROPOSED	Signed append-only log chains, cross-host replication, server reconciliation
`network-plugin-relay`	`@suaveplan/network-plugin-relay` (new)	PROPOSED	Cross-mesh federation: RelayRouter, HostBackboneTransport, CrossMeshEnvelope
`network-plugin-assignment`	`@suaveplan/network-plugin-assignment` (new)	PROPOSED	Mesh auto-placement: MeshCapacityTracker, AssignmentEngine, MeshBalancer
`network-plugin-partition`	`@suaveplan/network-plugin-partition` (new)	PROPOSED	Split-brain detection: PartitionDetector, QuorumResolver, MergeProtocol
`network-plugin-circuit-breaker`	`@suaveplan/network-plugin-circuit-breaker` (new)	PROPOSED	Mesh boundary circuit breaking with half-open probes
`network-plugin-qos`	`@suaveplan/network-plugin-qos` (new)	PROPOSED	Per-mesh bandwidth quotas, message priority classes, congestion monitoring
`network-plugin-migration`	`@suaveplan/network-plugin-migration` (new)	PROPOSED	Peer state migration between meshes, forwarding tunnels
`network-plugin-auth`	`@suaveplan/network-plugin-auth` (new)	PROPOSED	Mesh membership auth, capability tokens, cross-mesh trust
`enterprise-network-rename`	`@suaveplan/network-client` (renamed)	PROPOSED	Renames `enterprise-network` to resolve collision with shipped `@suaveplan/network`
`drive-network-integration`	— (spec-only)	PROPOSED	Clarifies drive-mesh ↔ content-delivery layering and registry consumption

Naming resolution

The enterprise-network proposal (dated 2026-04-24) originally targeted @suaveplan/network for HTTP/WebSocket utilities. The network-core proposal (dated 2026-04-29) also targeted @suaveplan/network for the mesh core. Because packages/network/network/ already contains shipped mesh-core code, enterprise-network is renamed to @suaveplan/network-client and moved to universal/network/network-client. The mesh core retains @suaveplan/network.

Key design decisions

Do not port suaveplan stubs: Genesis streams has real CryptoTransform, compressStream, lengthPrefixEncode/Decode. The suaveplan equivalents are documented stubs. Migration ports orchestration only.
Genesis primitives are the base: Crypto, storage, events, FSM, retry, rate-limiter, bitpacker, serialize — all exist in genesis and are consumed directly.
WebRTC for peer mesh: Browser peers need network-plugin-webrtc for signaling, data channels, and peer-to-peer chunk exchange.
Loose coupling via NetworkBus: Plugins communicate via typed events, not direct imports. This allows swapping transport or governance implementations without code changes.
Tiered system: HierarchicalTopologyImpl (Tier 0 Host → Tier 1 SubHost → Tier 2 Leaf), GovernedElection (metric/direct/hybrid), TransitionManager (handover FSM), FailoverCoordinator (alive→suspect→dead). 5a. Sessions overlay: SessionPlugin provides logical session trees on top of the physical mesh. Sessions enable GTA V-style free-roam → mission → phase nesting, per-session host nomination, capacity limits, and scoped message routing.
Bitpacker messaging: network-plugin-registry uses BitPacker for ~62-byte messages. network-plugin-protocol adds 13-byte binary header.
Sessions for gaming: network-plugin-session enables nested session hierarchies for multiplayer games: root session = free-roam open world, child sessions = missions/heists/races, grandchild sessions = mission phases or instanced interiors. Each session elects its own host and enforces its own capacity.
Multi-transport resilience: network-plugin-transport-manager maintains simultaneous WebRTC + WebSocket + HTTP transports. CRITICAL messages are sent redundantly on 2+ transports. BULK traffic is round-robined across healthy paths.
Cryptographic integrity: network-plugin-crypto-messages signs every host message with Ed25519. Sessions and meshes require server-signed tokens. Peer identity is verified via challenge-response. No session or mesh can be created without server authority.
Server offline resilience: network-plugin-server-bridge on Tier 0 hosts maintains a WebSocket to the central server. When offline, the mesh operates autonomously with token grace periods. Signed activity logs are buffered and replicated. When the server returns, logs are replayed and state is reconciled.
P2P content delivery: network-plugin-content-delivery distributes @suaveplan/packer file chunks across the mesh via WebRTC data channels. Chunks are stored in @suaveplan/drive with configurable redundancy (N copies per mesh). Latency-aware routing fetches from the nearest peer.
Signed audit trails: network-plugin-audit-mesh maintains hash-chained, host-signed, append-only logs of all session/mesh events. Logs are replicated to R sibling hosts for durability. The server retrieves and reconciles them on reconnection.
Drive integration: drive + drive-sharing + drive-webrtc form the storage layer. Hosts elected by the network layer coordinate chunk discovery.
Cross-mesh federation: network-plugin-relay enables Tier 0 hosts to route messages between meshes. network-plugin-assignment places new peers into the best mesh. network-plugin-partition detects and heals split-brain. network-plugin-circuit-breaker prevents cascade failures on relay paths.
Mesh auth & QoS: network-plugin-auth verifies peer identity before join and issues capability tokens. network-plugin-qos enforces bandwidth quotas and prioritizes control-plane traffic.
Migration: network-plugin-migration transfers peer state when rebalancing moves a peer between meshes.
Framework integrations (future): React hooks (useNetworkNode, useNetworkState, useNetworkEvent), Vue composables, Angular services, Node.js server integrations. These are deferred to dedicated integration packages after the core mesh stabilizes.

Source mapping

This suite derives from:

../suaveplan/enterprise/network.md
../suaveplan/enterprise/network-webrtc.md
../suaveplan/enterprise/network-governance.md
../suaveplan/enterprise/network-failover.md
../suaveplan/enterprise/network-registry.md
../suaveplan/enterprise/network-topology.md
../suaveplan/enterprise/network-protocol.md

Verification approach

Each child change has its own conformance tests and dep-graph tests. The suite is complete when:

All 13 packages pass bunx turbo lint typecheck test.
All 13 packages reach 100/100/100/100 coverage.
All 13 packages pass bun scripts/openspec-conformance.ts.
bun run gate (root) is green.

Migration impact

None — all additive. No existing genesis packages are modified.

9.3 KiB Raw Blame History