Initial Commit
This commit is contained in:
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
|
||||
Reference in New Issue
Block a user