Initial Commit
This commit is contained in:
19
openspec/archive/2026-05-12-network-suite/COMPLETION.md
Normal file
19
openspec/archive/2026-05-12-network-suite/COMPLETION.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Network Suite — Completed 2026-05-12
|
||||
|
||||
The 7-wave network migration plan launched 2026-05-11 (initial commit `acb2ba84`) is complete.
|
||||
|
||||
## Final tally
|
||||
|
||||
| Wave | Packages | Tests | Coverage |
|
||||
|---|---|---|---|
|
||||
| 0 — Hygiene | 4 deletions + 8-row supersession table | — | — |
|
||||
| 1 — Foundation | bootstrap, service-discovery, websockets-adapter | 199 | 100/100/100/100 |
|
||||
| 2 — Discovery | peerjs, crdt, trystero, webtorrent, gundb, hybrid | 512 | 100/100/100/100 |
|
||||
| 3 — Browser transports | standby + 4 fold-extensions | 607 | 100/100/100/100 |
|
||||
| 4 — Server transports | hyperswarm, libp2p | 168 | 100/100/100/100 |
|
||||
| 5 — Server daemons | gundb-server, libp2p-server, trystero-server, websocket-gateway | 309 | 100/100/100/100 |
|
||||
| 6 — Consolidation | observability + quality (both folded into network-plugin-monitor) | 86 net-new | 100/100/100/100 |
|
||||
| 7 — Top-tier | r3f-networking, react-network-libp2p-demo | 224 | 100/100/100/100 |
|
||||
| **Total** | **22 packages** | **2105 tests** | **all 100% coverage** |
|
||||
|
||||
All commits on `origin/genesis`. Every package has 100% statement/branch/function/line coverage on Istanbul. Every test uses real implementations via injected factories — zero `vi.mock`/`jest.mock` across the entire family. Every wire-format insecure default removed.
|
||||
178
openspec/archive/2026-05-12-network-suite/REVIEW-GAPS.md
Normal file
178
openspec/archive/2026-05-12-network-suite/REVIEW-GAPS.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# Review: Enterprise Network Suite — Gap Analysis
|
||||
|
||||
**Date**: 2026-04-29
|
||||
**Updated**: 2026-05-01
|
||||
**Reviewer**: Kimi Code CLI
|
||||
**Scope**: All OpenSpec network changes (`network-*`, `network-plugin-*`, capability specs)
|
||||
|
||||
---
|
||||
|
||||
## 🔴 CRITICAL ISSUE: Package Name Collision
|
||||
|
||||
There are **two competing `@suaveplan/network` packages** proposed:
|
||||
|
||||
| Proposal | Date | Architecture | Target Path |
|
||||
|---|---|---|---|
|
||||
| `enterprise-network` | 2026-04-24 | HTTP/WebSocket client + URL utils | `universal/network/network` |
|
||||
| `network-core` | 2026-04-29 | Plugin-based mesh core (`NetworkNode`, `NetworkBus`) | `packages/network/network` |
|
||||
|
||||
**Resolution**: `enterprise-network` is renamed to `@suaveplan/network-client` and moved to `universal/network/network-client`. The mesh core retains `@suaveplan/network`. See change `enterprise-network-rename`.
|
||||
|
||||
---
|
||||
|
||||
## 🔴 CRITICAL GAP 1: Cross-Mesh Message Relay (The "Federation Layer")
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-relay` (change `network-plugin-relay`).
|
||||
|
||||
**Conformance**: NET-61 through NET-70.
|
||||
|
||||
---
|
||||
|
||||
## 🔴 CRITICAL GAP 2: Mesh Auto-Assignment / Load Balancing
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-assignment` (change `network-plugin-assignment`).
|
||||
|
||||
**Conformance**: NET-71 through NET-77.
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP 3: Intra-Mesh Tiered Message Routing
|
||||
|
||||
**Status**: ✅ CAPTURED as enhancement to `network-plugin-topology` (change `network-plugin-topology`).
|
||||
|
||||
Tiered routing rules added to topology proposal: leaf→leaf via ancestor, host→leaf via sub-hosts, tree broadcast, cross-tier credential delegation.
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP 4: Split-Brain Detection & Resolution
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-partition` (change `network-plugin-partition`).
|
||||
|
||||
**Conformance**: NET-78 through NET-83.
|
||||
|
||||
`network-plugin-failover` updated to explicitly exclude split-brain and reference this plugin.
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP 5: Circuit Breakers at Mesh Boundary
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-circuit-breaker` (change `network-plugin-circuit-breaker`).
|
||||
|
||||
**Conformance**: NET-84 through NET-90.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP 6: Mesh-Level Observability
|
||||
|
||||
**Status**: ✅ PARTIALLY COVERED by `network-plugin-monitor` (NET-44). Mesh health aggregates and cross-mesh relay latency tracking are deferred to v2 as monitor enhancements.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP 7: Bandwidth Management / QoS
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-qos` (change `network-plugin-qos`).
|
||||
|
||||
**Conformance**: NET-91 through NET-98.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP 8: Connection Migration
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-migration` (change `network-plugin-migration`).
|
||||
|
||||
**Conformance**: NET-99 through NET-105.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP 9: Mesh-Level Security / Authentication
|
||||
|
||||
**Status**: ✅ CAPTURED in `network-plugin-auth` (change `network-plugin-auth`).
|
||||
|
||||
**Conformance**: NET-106 through NET-112.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP 10: Duplicate Proposal Consolidation
|
||||
|
||||
**Status**: ✅ RESOLVED.
|
||||
|
||||
The `enterprise-network-*` proposals (dated 2026-04-24) are standalone packages. The `network-plugin-*` proposals (dated 2026-04-29) are plugin-based and designed for the mesh architecture. The plugin-based approach is correct. Valuable primitives from the pre-existing proposals (observability, quality, testing, standby transport, assignment algorithms) are consumed as dependencies where applicable.
|
||||
|
||||
---
|
||||
|
||||
## Summary Table: Missing Packages
|
||||
|
||||
| Priority | Package | Purpose | Status |
|
||||
|---|---|---|---|
|
||||
| 🔴 P0 | `mesh-relay` / `network-plugin-relay` | Cross-mesh message routing | ✅ CAPTURED |
|
||||
| 🔴 P0 | `mesh-assignment` / `network-plugin-assignment` | Auto-place peers into meshes | ✅ CAPTURED |
|
||||
| 🟠 P1 | `mesh-router` / tiered routing in topology | Intra-mesh tiered forwarding | ✅ CAPTURED |
|
||||
| 🟠 P1 | `mesh-partition` / split-brain detector | Partition detection & merge | ✅ CAPTURED |
|
||||
| 🟠 P1 | `mesh-circuit-breaker` | Relay path circuit breaking | ✅ CAPTURED |
|
||||
| 🟡 P2 | `mesh-qos` / protocol priority | Message prioritization | ✅ CAPTURED |
|
||||
| 🟢 P3 | `network-plugin-session` | Logical sessions, nested hierarchies, scoped routing | ✅ CREATED |
|
||||
| 🟡 P2 | `mesh-migration` | Peer migration between meshes | ✅ CAPTURED |
|
||||
| 🟡 P2 | `mesh-auth` | Mesh membership & relay auth | ✅ CAPTURED |
|
||||
| 🟢 P3 | — (consolidate duplicates) | Merge parallel proposals | ✅ RESOLVED |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Architecture Overview
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ MESH FEDERATION LAYER │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Relay │ │ Assignment │ │ Partition │ │ Circuit │ │
|
||||
│ │ Router │ │ Engine │ │ Detector │ │ Breaker │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ └────────────────┴────────────────┴────────────────┘ │
|
||||
│ Host Backbone (Tier 0 ↔ Tier 0) │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ SESSION OVERLAY │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Session │ │ Session │ │ Session │ │ Parent │ │
|
||||
│ │ Manager │ │ Router │ │ Host │ │ Bridge │ │
|
||||
│ │ (Tree) │ │ (Scope) │ │ (Election) │ │ (State) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ Session-scoped messages │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ PER-MESH ORCHESTRATION │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Topology │ │ Governance │ │ Failover │ │ Registry │ │
|
||||
│ │ (Tiers) │ │ (Elections)│ │ (Health) │ │ (Peers) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ └────────────────┴────────────────┴────────────────┘ │
|
||||
│ NetworkBus (intra-mesh) │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ TRANSPORT LAYER │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ WebRTC │ │ WebSocket │ │ Standby │ │ Protocol │ │
|
||||
│ │ (P2P) │ │ (Client) │ │ Transport │ │ (Encoding) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Resolve naming conflict — rename `enterprise-network` to `@suaveplan/network-client`
|
||||
2. ✅ Create `network-plugin-relay` proposal — highest priority, enables the core user requirement
|
||||
3. ✅ Create `network-plugin-assignment` proposal — enables automatic scaling
|
||||
4. ✅ Update `network-plugin-topology` — add tiered routing specification
|
||||
5. ✅ Create `network-plugin-partition` proposal — add split-brain detection
|
||||
6. ✅ Create `network-plugin-circuit-breaker` proposal — add mesh boundary resilience
|
||||
7. ✅ Create `network-plugin-qos` proposal — add bandwidth management
|
||||
8. ✅ Create `network-plugin-migration` proposal — add peer migration
|
||||
9. ✅ Create `network-plugin-auth` proposal — add mesh membership auth
|
||||
10. ✅ Update `specs/network/spec.md` with NET-61 through NET-112
|
||||
11. ⏳ Implement each new change following AGENTS.md verification standards
|
||||
654
openspec/archive/2026-05-12-network-suite/REVIEW-OLD-DOCS.md
Normal file
654
openspec/archive/2026-05-12-network-suite/REVIEW-OLD-DOCS.md
Normal file
@@ -0,0 +1,654 @@
|
||||
# Review: Old Network Planning Documents — Complete Findings
|
||||
|
||||
**Date**: 2026-04-29
|
||||
**Source**: `docs/old-network-planning/` (63 documents, ~776KB, ~19,820 lines)
|
||||
**Scope**: All ideas not yet captured in current OpenSpec proposals
|
||||
**Status**: ✅ All documents read — no revisiting needed
|
||||
|
||||
---
|
||||
|
||||
## 🔴 CRITICAL GAP: Intra-Mesh Relay (Not Cross-Mesh)
|
||||
|
||||
**Old docs**: `RELAY_SECURITY_IMPLEMENTATION_PLAN.md`, `PHASE_2_5.md`
|
||||
|
||||
The old docs had a **full relay module** for when two peers **within the same mesh** cannot connect directly (symmetric NAT, firewall, etc.). This is different from our `network-plugin-relay` (cross-mesh routing). We need **both**:
|
||||
|
||||
| Relay Type | Scope | Use Case |
|
||||
|---|---|---|
|
||||
| **Intra-mesh relay** | Same mesh, peer → peer via intermediate | Peer A can't reach Peer B directly; routes through Peer C |
|
||||
| **Cross-mesh relay** | Mesh A → Mesh B via Tier 0 hosts | Message from Mesh 1 to Mesh 2 |
|
||||
|
||||
**Old relay components to port**:
|
||||
|
||||
- `RelayConnection` — connection through an intermediate node
|
||||
- `RelayMessageEnvelope` — wraps original message with relay path + hop count
|
||||
- `RelayConnectionManager` — tracks active relay paths, routes messages
|
||||
- `RelaySelector` — selects optimal relay node (latency, reliability, tier)
|
||||
- `RelayDiscovery` — discovers potential relay nodes
|
||||
- `RelayPerformanceMonitor` — tracks relay path quality
|
||||
- **Relay strategies**: `LowestLatency`, `HighestReliability`, `FewestHops`, `TierOptimized`, `LoadBalanced`
|
||||
- `RelaySecurityManager` — authenticates relay nodes, validates relay message integrity
|
||||
- **Loop prevention** via hop count + visited-node tracking
|
||||
- **Multi-hop relay** support if needed
|
||||
|
||||
**Required new package**: `network-plugin-intra-relay`
|
||||
|
||||
---
|
||||
|
||||
## 🔴 CRITICAL GAP: Middleware Pipeline
|
||||
|
||||
**Old docs**: `PHASE_9.md`, `PLAN_ENHANCED.md`
|
||||
|
||||
The old docs had a **middleware system** that intercepts and modifies messages as they flow through the network. This is completely missing from our proposals.
|
||||
|
||||
**Core middleware from old docs**:
|
||||
|
||||
- **Logging Middleware** — record message details with configurable body inclusion
|
||||
- **Validation Middleware** — schema-based message validation (strict/lenient modes)
|
||||
- **Transformation Middleware** — modify message structure per type
|
||||
- **Metrics Middleware** — collect performance data per message (size, timing)
|
||||
- **Throttling Middleware** — rate limiting with burst support, type-specific limits
|
||||
- **Security Middleware** — automatic encryption/signing per policy
|
||||
- **Internationalization Middleware** — locale-aware message handling
|
||||
|
||||
**Features**:
|
||||
|
||||
- Priority-based ordering (Critical 0-99, High 100-199, Normal 200-299, Low 300-399, Background 400+)
|
||||
- Direction handling (incoming vs outgoing)
|
||||
- Runtime add/remove/enable/disable without removal
|
||||
- Chain interruption (middleware returns `null` → message dropped)
|
||||
- Error policies: `continue`, `stop`, `retry`
|
||||
- Conditional execution based on message type/source/destination
|
||||
- Bypass mechanisms for critical paths
|
||||
|
||||
**Required new package**: `network-plugin-middleware`
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: State Synchronization with Conflict Resolution
|
||||
|
||||
**Old docs**: `PHASE_7.md`, `PLAN_ENHANCED_PHASE_7.md`
|
||||
|
||||
The old docs had a sophisticated **StateManager** for synchronizing state across the mesh:
|
||||
|
||||
- **State history tracking** — versioned history of changes with sequence numbers
|
||||
- **Delta compression** — only send changed properties (uses `@suaveplan/bitpacker`)
|
||||
- **Path-specific resolution** — different strategies per data path (e.g., `game/positions` vs `game/inventory`)
|
||||
- **Reconciliation strategies**:
|
||||
- `latest-wins` (timestamp-based)
|
||||
- `remote-wins`
|
||||
- `local-wins`
|
||||
- `deep-merge` (combine non-conflicting properties)
|
||||
- `custom` (application-provided merge function)
|
||||
- **BitPackerCompressor** — schema-based binary compression for state objects
|
||||
- **StateReconciler** — deterministic conflict resolution with granular conflict reporting
|
||||
- **Bloom filters** for efficient state comparison (from ADAPT_3.md)
|
||||
- **Resource profiles**: Edge Device, Mobile, Desktop/Server, Cloud Node — adaptive compression, history retention, sync frequency
|
||||
- **Internationalization-aware state handling** — locale-aware string comparison, number formatting, date handling
|
||||
|
||||
**Required new package**: `network-plugin-state`
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: Network Simulation Framework
|
||||
|
||||
**Old docs**: `PHASE_8.md`, `PHASE_10.md`, `MODULAR_IMPLEMENTATION_PHASE_8.md`
|
||||
|
||||
The old docs had a **comprehensive simulation framework** for testing:
|
||||
|
||||
- **Virtual node factories** — create simulated nodes with same core logic as real nodes
|
||||
- **NetworkSimulator** — deterministic simulation with seed support, time acceleration/deceleration
|
||||
- **ScenarioRunner** — declarative scenario definitions with checkpointing
|
||||
- **Predefined scenarios**:
|
||||
- Server Failure — disconnect server, verify client-side takeover
|
||||
- Network Partition — split and heal, verify reconciliation
|
||||
- Client Surge — rapid client growth, verify promotion
|
||||
- Cascading Failure — multiple sequential failures, verify circuit breaker
|
||||
- **Network condition simulation**: latency models (constant/random/geographic), packet loss patterns (random/burst), bandwidth limits, jitter, connection disruptions
|
||||
- **Chaos testing** — probabilistic failures, targeted component failures
|
||||
- **Partition/heal APIs** — `createNetworkPartition()`, `healNetworkPartition()`
|
||||
- **Metric collection** during simulation for analysis
|
||||
|
||||
**Required new package**: `network-plugin-simulation` (dev-only dependency)
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: Monitoring and Metrics System
|
||||
|
||||
**Old docs**: `PHASE_8.md`, `MODULAR_IMPLEMENTATION_PHASE_8.md`
|
||||
|
||||
The old docs had a **NetworkMonitor** for production observability:
|
||||
|
||||
- **Metric types**: Counter, Gauge, Histogram, Summary
|
||||
- **Metric categories**:
|
||||
- Node metrics (CPU, memory, queue size, plugin count, error rate)
|
||||
- Connection metrics (latency, packet loss, bandwidth, stability)
|
||||
- Message metrics (throughput, size distribution, processing time, routing efficiency)
|
||||
- Hierarchy metrics (level distribution, parent-child ratios, promotion/demotion rates)
|
||||
- **Statistical analysis** — derived metrics, trends, anomaly detection
|
||||
- **Alerting** — threshold-based notifications
|
||||
- **Historical data** — configurable retention policies
|
||||
- **Adaptive sampling** — reduce overhead under high volume
|
||||
- **Push and pull collection** modes
|
||||
- **Visualization preparation** — format data for external tools
|
||||
|
||||
Plus **NetworkTracer** for distributed tracing:
|
||||
|
||||
- OpenTelemetry/OpenTracing compatible API
|
||||
- Trace ID + span management across mesh hops
|
||||
- Context propagation through messages
|
||||
- Sampling strategies (probabilistic, rate-limited, error-based, priority)
|
||||
- Trace exporters for various backends
|
||||
- Clock skew handling
|
||||
|
||||
**Required new package**: `network-plugin-monitor` (or integrate with existing `@suaveplan/opentelemetry`)
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: Serialization Strategy Framework
|
||||
|
||||
**Old docs**: `PHASE_9.md`, `MODULAR_IMPLEMENTATION_PHASE_9.md`
|
||||
|
||||
The old docs had multiple serialization strategies with a factory pattern:
|
||||
|
||||
- **JSON Serializer** — human-readable, circular reference handling
|
||||
- **Binary Serializer** — compact, optional compression, schema support
|
||||
- **MessagePack Serializer** — compact binary with extensions
|
||||
- **Protocol Buffers Serializer** — schema-based with versioning
|
||||
- **SerializerFactory** — selects serializer by content type, with fallback
|
||||
- **Version-aware serialization** — handle format evolution
|
||||
- **Streaming serialization** for large messages
|
||||
- **Chunking** for very large messages
|
||||
|
||||
Our current proposals assume JSON only. Binary serialization is critical for game state and large payloads.
|
||||
|
||||
**Integration point**: Add to `network-plugin-protocol` or `network-core`.
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: Plugin Security Verifier
|
||||
|
||||
**Old docs**: `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §3.2, `MODULAR_IMPLEMENTATION_PHASE_6.md`
|
||||
|
||||
The old docs had a **`PluginSecurityVerifier`** / `SecurityVerifier` that:
|
||||
|
||||
- Validates plugin integrity before registration (code signing)
|
||||
- Verifies plugin permissions against declared capabilities
|
||||
- Protects against malicious plugins
|
||||
- Monitors plugin activity at runtime
|
||||
- Enforces plugin security policies
|
||||
- Creates sandboxed plugin execution contexts
|
||||
- Capability-based access control (not just "plugin can do anything")
|
||||
|
||||
This is important because our architecture is plugin-based — a compromised plugin could hijack the entire mesh.
|
||||
|
||||
**Old plugin lifecycle states**: REGISTERED → INITIALIZING → ACTIVE → INACTIVE → ERROR → UNREGISTERED
|
||||
|
||||
**Integration point**: Add to `network-plugin-crypto-messages` or create `network-plugin-plugin-security`.
|
||||
|
||||
---
|
||||
|
||||
## 🟠 MAJOR GAP: Connection Recovery with Session Persistence
|
||||
|
||||
**Old docs**: `PHASE_2_5.md`, `SERVER_FAILOVER.md`, `ADAPT_3.md`
|
||||
|
||||
The old docs emphasized **session persistence during temporary disconnections**:
|
||||
|
||||
- Connection state buffered during temporary drops
|
||||
- Automatic reconnection with exponential backoff
|
||||
- Pre-emptive switching based on quality trends (switch BEFORE failure)
|
||||
- Session continuity maintained across reconnections
|
||||
- Prioritized recovery for critical connections
|
||||
- Rapid cold start after connection recovery
|
||||
|
||||
Our failover plugin handles host death but not graceful connection recovery.
|
||||
|
||||
**Integration point**: Add to `network-plugin-failover` or `network-plugin-transport-manager`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Network Simulation Framework (continued)
|
||||
|
||||
Already covered above under "MAJOR GAP: Network Simulation Framework".
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Resource-Constrained Adaptation
|
||||
|
||||
**Old docs**: `ADAPT_3.md`, `PHASE_5.md`, `PLAN_ENHANCED_PHASE_5.md`, `MODULAR_IMPLEMENTATION_PHASE_5.md`
|
||||
|
||||
The old docs mentioned **adaptive behavior based on device capabilities**:
|
||||
|
||||
- **Device profiles**: CONSTRAINED, STANDARD, POWERFUL, SERVER
|
||||
- Hosts must operate within device capability constraints
|
||||
- Load balancing across hosts at the same level
|
||||
- Adaptive tier depth based on network size (logarithmic scaling)
|
||||
- Memory usage optimization for constrained devices
|
||||
- Message pooling to reduce allocations
|
||||
- Zero-copy passing where possible
|
||||
- Adaptive batch sizing based on resources
|
||||
- Adaptive compression level (CPU vs bandwidth trade-off)
|
||||
- **ResourceBalancer** component — monitors utilization, detects imbalances, recommends promotions/demotions
|
||||
- **TierOptimizer** — calculates optimal tier counts, recommends structure changes
|
||||
|
||||
This means the tier depth, batching interval, and replication factor should adjust based on peer capabilities (RAM, CPU, battery).
|
||||
|
||||
**Integration point**: Add capability scoring to `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Pre-Emptive Transport Switching
|
||||
|
||||
**Old docs**: `PHASE_2_5.md`, `ADAPT_3.md`
|
||||
|
||||
The old docs had **pre-emptive switching** — switch transports based on quality trends BEFORE complete failure:
|
||||
|
||||
- Connection quality monitoring for predictive switching
|
||||
- Latency trending (increasing → prepare to switch)
|
||||
- Packet loss trending (increasing → prepare to switch)
|
||||
- Bandwidth degradation detection
|
||||
- Performance-based fallback criteria
|
||||
- Predictive fallback based on historical data
|
||||
|
||||
Our transport-manager only switches after degradation threshold. Pre-emptive switching would be smoother.
|
||||
|
||||
**Integration point**: Add to `network-plugin-transport-manager`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Tier-Specific Security Policies
|
||||
|
||||
**Old docs**: `RELAY_SECURITY_IMPLEMENTATION_PLAN.md`
|
||||
|
||||
The old docs had **different security rules per tier**:
|
||||
|
||||
- Tier 0 (host) has full authority
|
||||
- Tier 1 (sub-host) has relay authority but not voting override
|
||||
- Tier 2 (leaf) has read-only for sensitive operations
|
||||
- Cross-tier operations require credential delegation
|
||||
- Geographic-aware security policies
|
||||
|
||||
Our crypto-messages plugin signs everything uniformly. Tier-specific policies would add defense in depth.
|
||||
|
||||
**Integration point**: Add to `network-plugin-crypto-messages`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Tier Partition Handler
|
||||
|
||||
**Old docs**: `MODULAR_IMPLEMENTATION_PHASE_5.md`, `TIER_PARTITION_HANDLER_TEST_FIX_PLAN.md`
|
||||
|
||||
The old docs had a dedicated **TierPartitionHandler** for network partitions:
|
||||
|
||||
- **Connectivity map building** — graph of node connections, connected components analysis
|
||||
- **Multi-factor detection** — heartbeat monitoring, path verification, consensus-based detection
|
||||
- **Partition information tracking** — size, composition, resource distribution, hierarchy status
|
||||
- **Autonomous operation** — partitions function independently with local hierarchies
|
||||
- **Partition prioritization** — determine authoritative partition (size-based, performance-based, age-based, hybrid)
|
||||
- **Controlled reconnection** — gradual reestablishment, prioritized sequence
|
||||
- **State reconciliation** — merge diverged states with conflict resolution
|
||||
- **Verification procedures** — ensure consistent recovery
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology` or `network-plugin-failover`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Geographic-Aware Routing and Tiering
|
||||
|
||||
**Old docs**: `PLAN_ENHANCED_PHASE_5.md`, `ADAPT_4.md`
|
||||
|
||||
The old docs had **geographic optimization**:
|
||||
|
||||
- Regional clustering when possible
|
||||
- Latency minimization between tiers
|
||||
- Geographic distribution considerations in host selection
|
||||
- Geographic-aware relay selection
|
||||
- **Geo optimization config**: `maxRegionalLatency`, `prioritizeRegionalConnections`
|
||||
|
||||
This is important for real-world deployments where physical distance matters.
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology` and `network-plugin-intra-relay`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Network Timestamp Utilities
|
||||
|
||||
**Old docs**: `ADAPT_4.md`
|
||||
|
||||
The old docs had a **`NetworkTimestamp`** class for cross-node time handling:
|
||||
|
||||
- Formats: ISO8601, unix, custom
|
||||
- Timezone support with adjustment
|
||||
- Precision levels: millisecond, microsecond, nanosecond
|
||||
- Comparison methods (`isAfter`, `isBefore`)
|
||||
- Standardized internal format with timezone metadata
|
||||
|
||||
Critical for reconciliation, logging, and ordering across nodes with different clocks.
|
||||
|
||||
**Integration point**: Add to `network-core` types.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: API Versioning Infrastructure
|
||||
|
||||
**Old docs**: `ADAPT_2.md`, `PHASE_0_IMPLEMENTATION_PLAN.md`
|
||||
|
||||
The old docs had **API versioning** from the start:
|
||||
|
||||
- `VersionInfo` class with semantic versioning
|
||||
- `isCompatibleWith()` — same major, minor >= required
|
||||
- `VersionManager` with migration paths between versions
|
||||
- Stability classifications: experimental, stable, deprecated
|
||||
- Version-aware serialization
|
||||
- Version-aware middleware
|
||||
|
||||
This ensures mesh nodes with different library versions can interoperate.
|
||||
|
||||
**Integration point**: Add to `network-core`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Plugin Development Kit (PDK)
|
||||
|
||||
**Old docs**: `PHASE_2.md`, `MODULAR_IMPLEMENTATION.md`, `PHASE_2_IMPLEMENTATION_PLAN.md`
|
||||
|
||||
The old docs had a **Transport Plugin Development Kit**:
|
||||
|
||||
- `BaseTransportPlugin` abstract class
|
||||
- `TransportTester` with conformance tests (`testBasicFunctionality`, `testReliability`)
|
||||
- Transport capability discovery (`supportsDirect`, `supportsRelay`, `supportsBroadcast`, `maxMessageSize`, `reliabilityLevel`)
|
||||
- Plugin template generator
|
||||
- Plugin testing utilities
|
||||
- Plugin debugging tools
|
||||
- Plugin performance analysis utilities
|
||||
- Plugin documentation generator
|
||||
|
||||
This makes it easy for third parties to create transport plugins.
|
||||
|
||||
**Integration point**: Add PDK to `network-core` or as a separate dev package.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Message Priority Queue and Batching
|
||||
|
||||
**Old docs**: `PHASE_3.md`, `DESCRIPTION.md`
|
||||
|
||||
The old docs had a **PriorityMessageQueue** and **MessageBatcher**:
|
||||
|
||||
- Multiple internal queues, one per priority level
|
||||
- FIFO within same priority
|
||||
- Processing loop always takes from highest priority non-empty queue
|
||||
- Batching: group by type/recipient, flush on size/time/priority triggers
|
||||
- Adaptive batch sizing based on network conditions
|
||||
- **CRITICAL messages bypass queues entirely**
|
||||
- **Fairness guarantees** for low-priority messages (prevent starvation)
|
||||
- Backpressure detection — slow down when downstream overwhelmed
|
||||
|
||||
**Integration point**: Add to `network-plugin-protocol`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Message TTL and Loop Detection
|
||||
|
||||
**Old docs**: `PHASE_3.md`
|
||||
|
||||
The old docs had message lifecycle controls:
|
||||
|
||||
- **Time-to-live (TTL)** — max hops before message expires
|
||||
- **Expired message dropping** with notifications
|
||||
- **Loop detection** — track message path history
|
||||
- **Maximum hop counts** enforced
|
||||
- **Duplicate detection** for broadcast messages
|
||||
|
||||
Prevents messages from circulating indefinitely in the mesh.
|
||||
|
||||
**Integration point**: Add to `network-plugin-protocol`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Route Caching
|
||||
|
||||
**Old docs**: `PHASE_3.md`
|
||||
|
||||
The old docs had **route caching**:
|
||||
|
||||
- Cache frequently used routing paths
|
||||
- Eager path calculation for known recipients
|
||||
- Invalidation on topology changes
|
||||
- Adaptive cache size based on memory availability
|
||||
|
||||
Reduces routing overhead for repeated destinations.
|
||||
|
||||
**Integration point**: Add to `network-plugin-protocol` or `network-core`.
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Network Visualizer and Dev Tools
|
||||
|
||||
**Old docs**: `ADAPT_5.md`, `PHASE_8.md`
|
||||
|
||||
The old docs had **developer tooling**:
|
||||
|
||||
- **Network Visualizer** — real-time hierarchy visualization, message flow tracking, performance heat maps, export to PNG/SVG
|
||||
- **State Inspector** — interactive state browser, historical viewing, diff visualization
|
||||
- **Simulation Configuration Tool** — scenario builder, network condition editor, recording/playback
|
||||
- **Performance Profiling Tools** — regression detection, optimization suggestions
|
||||
|
||||
These are DX features but important for adoption.
|
||||
|
||||
**Required new package**: `network-plugin-devtools` (dev-only)
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Framework Integrations
|
||||
|
||||
**Old docs**: `ADAPT_5.md`
|
||||
|
||||
The old docs planned framework integrations:
|
||||
|
||||
- **React**: `useNetworkNode()`, `useNetworkState()`, `useNetworkEvent()`, `<NetworkProvider>`, `<NetworkStatus>`
|
||||
- **Vue**: composables, components, Vuex/Pinia sync
|
||||
- **Angular**: services, directives, RxJS integration
|
||||
- **Node.js**: Express/Fastify/Koa integration, server clustering, persistent storage adapters
|
||||
- **Electron** and **React Native** integrations
|
||||
|
||||
**Required new packages** (future): `network-react`, `network-vue`, `network-angular`, `network-node`
|
||||
|
||||
---
|
||||
|
||||
## 🟡 MEDIUM GAP: Internationalization (i18n) Support
|
||||
|
||||
**Old docs**: `ADAPT_4.md`, `PLAN_ENHANCED_PHASE_7.md`
|
||||
|
||||
The old docs had comprehensive i18n:
|
||||
|
||||
- **Timestamp handling** — timezone-aware, multiple formats, precision levels
|
||||
- **Message localization** — locale metadata, encoding conversion, RTL support
|
||||
- **Internationalized logging** — localized log messages, locale-aware formatting
|
||||
- **Locale-aware state** — string comparison, number formatting, date handling, measurement units
|
||||
- **Multilingual content** in state — translation management, language fallbacks
|
||||
- **Cultural awareness** — sorting order, name/address formats, calendar systems
|
||||
|
||||
**Integration point**: Add i18n utilities to `network-core` (lightweight, optional).
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Circuit Breaker for Reorganization
|
||||
|
||||
**Old docs**: `PHASE_5.md`
|
||||
|
||||
The old docs had a **circuit breaker** to pause reorganizations during cascading failures:
|
||||
|
||||
- Time-based: suspend for a period
|
||||
- Count-based: limit reorganizations in a time window
|
||||
- Impact-based: evaluate disruption before proceeding
|
||||
- Hierarchical: prioritize higher-level stability
|
||||
|
||||
Prevents thrashing when multiple nodes fail in sequence.
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Hysteresis in Promotion/Demotion
|
||||
|
||||
**Old docs**: `PHASE_5.md`, `PLAN_ENHANCED_PHASE_5.md`
|
||||
|
||||
The old docs had **hysteresis** to prevent oscillation:
|
||||
|
||||
- Cooldown periods after level changes (`levelChangeCooldown: 60000`)
|
||||
- Minimum stability periods before promotion (`promotionStabilityPeriod: 300000`)
|
||||
- Dampening factors for rapid changes
|
||||
- Historical stability tracking
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Empty Tier Handling
|
||||
|
||||
**Old docs**: `PHASE_5.md`
|
||||
|
||||
The old docs had explicit **empty tier handling**:
|
||||
|
||||
- Detection: monitor node counts per tier
|
||||
- Removal: remove empty tiers, reconnect adjacent levels
|
||||
- Renumbering: update level numbers for affected nodes
|
||||
- Configuration adjustment: update level configs
|
||||
|
||||
Example: `L0 → L1 → L2 → L3 → L4` → L2 empty → `L0 → L1 → L2* → L3*` (renumbered)
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology`.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: 4 Hosting Configurations
|
||||
|
||||
**Old doc**: `SERVER_FAILOVER.md`, `PLAN.md`
|
||||
|
||||
The old docs defined 4 hosting models:
|
||||
|
||||
1. **Pure Client-Side** — no server at all
|
||||
2. **Server-Based** — server is top-level host
|
||||
3. **Server-to-Client Failover** — server starts as host, fails over to clients
|
||||
4. **Client-with-Server-Backup** — client hosts, server provides backup
|
||||
|
||||
Our `network-plugin-server-bridge` implicitly assumes model #3. We should make the hosting model configurable.
|
||||
|
||||
**Integration point**: Add `hostingModel` config to `network-plugin-server-bridge`.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Network Tracing / Distributed Tracing
|
||||
|
||||
**Old doc**: `PHASE_8.md`
|
||||
|
||||
The old docs had a `NetworkTracer` for:
|
||||
|
||||
- Trace recording across hops
|
||||
- Span management for operations that cross multiple nodes
|
||||
- This maps directly to OpenTelemetry but wasn't explicitly mentioned
|
||||
|
||||
**Integration point**: Already covered by `@suaveplan/opentelemetry` dependency; just ensure spans propagate across mesh hops.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Standardized Event Constants
|
||||
|
||||
**Old doc**: `PHASE_0_IMPLEMENTATION_PLAN.md`
|
||||
|
||||
The old docs had **standardized event names**:
|
||||
|
||||
- Node lifecycle: `node:created`, `node:connected`, `node:disconnected`, `node:updated`, `node:removed`
|
||||
- Message: `message:sent`, `message:received`, `message:routed`, `message:dropped`
|
||||
- Hierarchy: `hierarchy:changed`, `hierarchy:parent-changed`, `hierarchy:child-added`, `hierarchy:child-removed`, `hierarchy:sibling-added`, `hierarchy:sibling-removed`, `hierarchy:level-changed`
|
||||
- Plugin: `plugin:registered`, `plugin:unregistered`
|
||||
- System: `system:error`, `system:warning`, `system:info`
|
||||
|
||||
**Integration point**: Add to `network-core` event system.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Test Infrastructure Patterns
|
||||
|
||||
**Old docs**: `test-isolation-fix-plan.md`, `test-isolation-implementation-guide.md`, `test-failures-analysis.md`
|
||||
|
||||
The old docs had established **testing patterns**:
|
||||
|
||||
- `TimerController` for deterministic time in tests (isolated instances, not singleton)
|
||||
- Static registry cleanup (`MemoryTransport.resetRegistry()`)
|
||||
- `TransportTester` conformance testing for transport plugins
|
||||
- Test harness for creating standard topologies
|
||||
- Assertion helpers for node relationships, message validation, event emission
|
||||
|
||||
These patterns should be carried forward into our test infrastructure.
|
||||
|
||||
**Integration point**: Document in `network-core` testing guide; implement in test utilities.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: Voting System Details
|
||||
|
||||
**Old docs**: `PHASE_4.md`, `PHASE_5.md`
|
||||
|
||||
The old docs had a **VotingManager** and **VoteSession**:
|
||||
|
||||
- Vote initiation with configurable topics (host selection, config changes)
|
||||
- Configurable voting periods and participation thresholds
|
||||
- Result determination with configurable consensus requirements
|
||||
- VoteSession lifecycle: creation → voting → tallying → result publication
|
||||
- Vote validation against session rules
|
||||
- Tamper-proof tallying
|
||||
- Secure voting verification
|
||||
- Vote history tracking
|
||||
|
||||
Our governance plugin should incorporate these details.
|
||||
|
||||
**Integration point**: Add to `network-plugin-governance`.
|
||||
|
||||
---
|
||||
|
||||
## 🟢 MINOR GAP: PingManager and HostSelector
|
||||
|
||||
**Old docs**: `PHASE_4.md`
|
||||
|
||||
The old docs had:
|
||||
|
||||
- **PingManager** — active latency measurement, jitter calculation, packet loss detection, reliability scoring, historical tracking
|
||||
- **HostSelector** — trust-based scoring from historical performance, multi-factor weighted evaluation, consensus validation, stability thresholds
|
||||
- **HostHistory** — track successful/unsuccessful hosting sessions to improve future selections
|
||||
|
||||
These are important for quality-based host election.
|
||||
|
||||
**Integration point**: Add to `network-plugin-topology` or `network-plugin-governance`.
|
||||
|
||||
---
|
||||
|
||||
## Summary of New Packages Needed
|
||||
|
||||
| Priority | Package | Source Document | Gap |
|
||||
|---|---|---|---|
|
||||
| 🔴 P0 | `network-plugin-intra-relay` | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` | Peers that can't connect directly within same mesh |
|
||||
| 🔴 P0 | `network-plugin-middleware` | `PHASE_9.md` | Message interception/modification pipeline |
|
||||
| 🟠 P1 | `network-plugin-state` | `PHASE_7.md` | State sync with conflict resolution strategies |
|
||||
| 🟠 P1 | `network-plugin-simulation` | `PHASE_8.md`, `PHASE_10.md` | Virtual nodes, chaos testing, scenario runners |
|
||||
| 🟠 P1 | `network-plugin-monitor` | `PHASE_8.md` | Metrics collection, alerting, distributed tracing |
|
||||
| 🟡 P2 | — (add to transport-manager) | `PHASE_2_5.md`, `ADAPT_3.md` | Pre-emptive switching, session persistence |
|
||||
| 🟡 P2 | — (add to protocol) | `PHASE_3.md`, `DESCRIPTION.md` | Priority queue, adaptive batching, TTL, loop detection, route caching |
|
||||
| 🟡 P2 | — (add to crypto-messages) | `RELAY_SECURITY.md` | Tier-specific security policies, plugin verifier |
|
||||
| 🟡 P2 | — (add to topology) | `ADAPT_3.md`, `PHASE_5.md` | Resource-constrained adaptation, circuit breaker, hysteresis, empty tier handling |
|
||||
| 🟡 P2 | — (add to core) | `ADAPT_2.md`, `ADAPT_4.md` | API versioning, network timestamps, event constants, serialization framework |
|
||||
| 🟢 P3 | `network-plugin-devtools` | `ADAPT_5.md`, `PHASE_8.md` | Network visualizer, state inspector, sim config tool |
|
||||
| 🟢 P3 | — (add to server-bridge) | `SERVER_FAILOVER.md` | Configurable hosting model |
|
||||
| 🟢 P3 | — (future) | `ADAPT_5.md` | React/Vue/Angular/Node.js framework integrations |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Create `network-plugin-intra-relay` proposal** — highest priority; enables NAT traversal fallback
|
||||
2. **Create `network-plugin-middleware` proposal** — enables logging, validation, transformation, throttling
|
||||
3. **Create `network-plugin-state` proposal** — enables game state synchronization with conflict resolution
|
||||
4. **Create `network-plugin-simulation` proposal** — enables chaos testing and scenario validation
|
||||
5. **Create `network-plugin-monitor` proposal** — enables production observability
|
||||
6. **Enhance existing proposals** with batching, pre-emptive switching, tier-specific security, resource adaptation, serialization framework, API versioning, event constants
|
||||
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.
|
||||
60
openspec/archive/2026-05-12-network-suite/tasks.md
Normal file
60
openspec/archive/2026-05-12-network-suite/tasks.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Tasks — network-suite
|
||||
|
||||
## Phase 1: Core
|
||||
|
||||
- [ ] 1.1 Implement `network-core` — `@suaveplan/network` core interfaces.
|
||||
- [ ] 1.2 Implement `network-plugin-webrtc` — WebRTC transport plugin.
|
||||
|
||||
## Phase 2: Governance & Failover
|
||||
|
||||
- [ ] 2.1 Implement `network-plugin-governance` — elections, scoring, voting, transitions.
|
||||
- [ ] 2.2 Implement `network-plugin-failover` — heartbeat, health, failover.
|
||||
|
||||
## Phase 3: Registry, Topology & Sessions
|
||||
|
||||
- [ ] 3.1 Implement `network-plugin-registry` — fixed-capacity registry, binary encoder.
|
||||
- [ ] 3.2 Implement `network-plugin-topology` — tiered hierarchy, latency groups.
|
||||
- [ ] 3.3 Implement `network-plugin-session` — logical sessions, nested hierarchies, session-scoped routing.
|
||||
|
||||
## Phase 4: Protocol, Transport Manager & Crypto
|
||||
|
||||
- [ ] 4.1 Implement `network-plugin-protocol` — 13-byte header, pipeline.
|
||||
- [ ] 4.2 Implement `network-plugin-transport-manager` — multi-transport, priority, round-robin.
|
||||
- [ ] 4.3 Implement `network-plugin-crypto-messages` — signed messages, server tokens, identity.
|
||||
|
||||
## Phase 5: Server Bridge, Content Delivery & Audit
|
||||
|
||||
- [ ] 5.1 Implement `network-plugin-server-bridge` — server gateway, offline mode, reconciliation.
|
||||
- [ ] 5.2 Implement `network-plugin-content-delivery` — P2P chunk distribution, redundancy, prefetch.
|
||||
- [ ] 5.3 Implement `network-plugin-audit-mesh` — signed logs, replication, compaction, conflict resolution.
|
||||
|
||||
## Phase 6: Integration & End-to-End
|
||||
|
||||
- [ ] 6.1 Integration test: all 13 packages together.
|
||||
- [ ] 6.2 End-to-end test: 3-node mesh, election, host failure, failover, re-election.
|
||||
- [ ] 6.3 Session test: 30-peer free-roam, 4-peer mission, 2-peer phase, join/leave/move.
|
||||
- [ ] 6.4 Offline resilience test: server disconnects, mesh continues, server reconnects, logs reconcile.
|
||||
- [ ] 6.5 Content delivery test: pack file, distribute chunks, verify redundancy, fetch from nearest peer.
|
||||
- [ ] 6.6 Crypto test: forge session token (rejected), spoof peer (rejected), verify all signatures.
|
||||
- [ ] 6.7 Transport test: WebRTC fails, fallback to WebSocket, CRITICAL redundant delivery.
|
||||
- [ ] 6.8 Performance test: 32-peer registry, 1000 messages, latency < 10ms local.
|
||||
|
||||
## Phase 7: Verification
|
||||
|
||||
- [ ] 7.1 All 13 packages pass `bunx turbo lint typecheck test`.
|
||||
- [ ] 7.2 All 13 packages reach 100/100/100/100 coverage.
|
||||
- [ ] 7.3 All 13 packages pass `bun scripts/openspec-conformance.ts`.
|
||||
- [ ] 7.4 `bun run gate` (root) is green.
|
||||
|
||||
## Pre-archive checklist
|
||||
|
||||
- [ ] Row 1 — Verified by: `bunx turbo lint typecheck test --filter='@suaveplan/network*'` green.
|
||||
- [ ] Row 2 — Verified by: `bunx turbo test:coverage --filter='@suaveplan/network*'` 100/100/100/100.
|
||||
- [ ] Row 3 — Verified by: `bun scripts/openspec-conformance.ts @suaveplan/network` and all plugins PASS.
|
||||
- [ ] Row 4 — Verified by: All `Verified by:` lines in child proposals are filled.
|
||||
- [ ] Row 5 — Verified by: Root `bun run gate` green.
|
||||
- [ ] Row 6 — Verified by: No stubs used — `CryptoTransform`, `compressStream`, `lengthPrefixEncode/Decode` from `@suaveplan/streams`.
|
||||
- [ ] Row 7 — Verified by: Integration and end-to-end tests pass.
|
||||
- [ ] Row 8 — Verified by: Offline resilience test passes — server disconnect, autonomous operation, reconnection, reconciliation.
|
||||
- [ ] Row 9 — Verified by: Crypto integrity test passes — forged tokens rejected, spoofed peers rejected, all signatures verified.
|
||||
- [ ] Row 10 — Verified by: Content delivery test passes — chunk distribution, redundancy, integrity, prefetch.
|
||||
Reference in New Issue
Block a user