# 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