179 lines
11 KiB
Markdown
179 lines
11 KiB
Markdown
# 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
|