SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9b28db724f7c99ad304963ee7d8a876190dd4167
suaveplan/openspec/archive/2026-05-12-network-suite/REVIEW-OLD-DOCS.md
admin fbc70f96e6 Initial Commit
2026-05-27 23:29:53 +01:00

26 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink