Initial Commit
This commit is contained in:
88
openspec/archive/2026-05-12-network-suite/proposal.md
Normal file
88
openspec/archive/2026-05-12-network-suite/proposal.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 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
|
||||
|
||||
1. **Do not port suaveplan stubs**: Genesis `streams` has real `CryptoTransform`, `compressStream`, `lengthPrefixEncode/Decode`. The suaveplan equivalents are documented stubs. Migration ports orchestration only.
|
||||
2. **Genesis primitives are the base**: Crypto, storage, events, FSM, retry, rate-limiter, bitpacker, serialize — all exist in genesis and are consumed directly.
|
||||
3. **WebRTC for peer mesh**: Browser peers need `network-plugin-webrtc` for signaling, data channels, and peer-to-peer chunk exchange.
|
||||
4. **Loose coupling via `NetworkBus`**: Plugins communicate via typed events, not direct imports. This allows swapping transport or governance implementations without code changes.
|
||||
5. **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.
|
||||
6. **Bitpacker messaging**: `network-plugin-registry` uses `BitPacker` for ~62-byte messages. `network-plugin-protocol` adds 13-byte binary header.
|
||||
7. **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.
|
||||
8. **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.
|
||||
9. **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.
|
||||
10. **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.
|
||||
11. **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.
|
||||
12. **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.
|
||||
13. **Drive integration**: `drive` + `drive-sharing` + `drive-webrtc` form the storage layer. Hosts elected by the network layer coordinate chunk discovery.
|
||||
14. **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.
|
||||
15. **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.
|
||||
16. **Migration**: `network-plugin-migration` transfers peer state when rebalancing moves a peer between meshes.
|
||||
17. **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:
|
||||
|
||||
1. All 13 packages pass `bunx turbo lint typecheck test`.
|
||||
2. All 13 packages reach 100/100/100/100 coverage.
|
||||
3. All 13 packages pass `bun scripts/openspec-conformance.ts`.
|
||||
4. `bun run gate` (root) is green.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — all additive. No existing genesis packages are modified.
|
||||
Reference in New Issue
Block a user