Files

2026-05-27 23:29:53 +01:00

11 KiB

Raw Permalink Blame History

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

┌─────────────────────────────────────────────────────────────────────────────┐
│                        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

✅ Resolve naming conflict — rename enterprise-network to @suaveplan/network-client
✅ Create network-plugin-relay proposal — highest priority, enables the core user requirement
✅ Create network-plugin-assignment proposal — enables automatic scaling
✅ Update network-plugin-topology — add tiered routing specification
✅ Create network-plugin-partition proposal — add split-brain detection
✅ Create network-plugin-circuit-breaker proposal — add mesh boundary resilience
✅ Create network-plugin-qos proposal — add bandwidth management
✅ Create network-plugin-migration proposal — add peer migration
✅ Create network-plugin-auth proposal — add mesh membership auth
✅ Update specs/network/spec.md with NET-61 through NET-112
⏳ Implement each new change following AGENTS.md verification standards

11 KiB Raw Permalink Blame History