26 KiB
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 nodeRelayMessageEnvelope— wraps original message with relay path + hop countRelayConnectionManager— tracks active relay paths, routes messagesRelaySelector— selects optimal relay node (latency, reliability, tier)RelayDiscovery— discovers potential relay nodesRelayPerformanceMonitor— 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/positionsvsgame/inventory) - Reconciliation strategies:
latest-wins(timestamp-based)remote-winslocal-winsdeep-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:
VersionInfoclass with semantic versioningisCompatibleWith()— same major, minor >= requiredVersionManagerwith 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:
BaseTransportPluginabstract classTransportTesterwith 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:
- Pure Client-Side — no server at all
- Server-Based — server is top-level host
- Server-to-Client Failover — server starts as host, fails over to clients
- 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:
TimerControllerfor deterministic time in tests (isolated instances, not singleton)- Static registry cleanup (
MemoryTransport.resetRegistry()) TransportTesterconformance 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
- Create
network-plugin-intra-relayproposal — highest priority; enables NAT traversal fallback - Create
network-plugin-middlewareproposal — enables logging, validation, transformation, throttling - Create
network-plugin-stateproposal — enables game state synchronization with conflict resolution - Create
network-plugin-simulationproposal — enables chaos testing and scenario validation - Create
network-plugin-monitorproposal — enables production observability - Enhance existing proposals with batching, pre-emptive switching, tier-specific security, resource adaptation, serialization framework, API versioning, event constants