suaveplan/docs/network/implementation-status.md

# Network — Implementation Status

Source of truth: [`STATUS.md`](../../STATUS.md), [`openspec/specs/network/spec.md`](../../openspec/specs/network/spec.md), and the in-flight changes under `openspec/changes/network-*` and `openspec/changes/enterprise-network-*`.

## Shipped on `genesis` (genesis-original — newer plugin model)

| Package | Notes |
| --- | --- |
| `@suaveplan/network` | The substrate. `NetworkNode`, `NetworkPlugin`, `NetworkBus`, `MessageEnvelope`, `Transport`, `MessageRouter`, `PluginManager`, `NetworkTimestamp`, `VersionInfo`. NET-01..05, NET-12, NET-53..55. |
| `@suaveplan/network-plugin-protocol` | 13-byte binary header, encoder/decoder, pipeline, priority queue, batcher, TTL, loop detector, three serializers (JSON/Binary/MessagePack). NET-15..17, NET-25, NET-45, NET-57..59. |
| `@suaveplan/network-plugin-registry` | Fixed-capacity peer registry with bitpacker delta sync. NET-09, NET-13. |
| `@suaveplan/network-transport-webrtc` | WebRTC transport + PingManager. NET-06..07. |
| `@suaveplan/network-failover` | Heartbeat FSM, failover trigger. NET-10. |
| `@suaveplan/network-governance` | Election, voting, host selection. NET-08. |
| `@suaveplan/network-topology` | Tier 0/1/2 graph. NET-11. |
| `@suaveplan/network-transport-websockets` | WebSocket transport, queue, heartbeat, adapters. |
| `@suaveplan/network-testing` | MemoryTransport, FakeWebSocketAdapter, ConditionSimulator, TestPeer factory, EventCapture. |

## Pending — to be ported from `main` (older naming)

| Package | Description (from main `README.md`) |
| --- | --- |
| `@suaveplan/network-protocol` | Network protocol abstractions. **Older naming — most content already in `network-plugin-protocol`.** |
| `@suaveplan/network-registry` | Network service/peer registry. **Older naming — most content already in `network-plugin-registry`.** |
| `@suaveplan/network-webrtc` | WebRTC peer-to-peer networking. **Older naming — most content in `network-transport-webrtc`.** |
| `@suaveplan/network-libp2p` | libp2p-based decentralized networking. |
| `@suaveplan/network-libp2p-server` | libp2p server with auto-relay. |
| `@suaveplan/network-hyperswarm` | Hyperswarm DHT networking. |
| `@suaveplan/network-trystero-server` | Trystero serverless P2P "server" relay. |
| `@suaveplan/network-gundb-server` | Gun.js relay peer. |
| `@suaveplan/network-discovery-{crdt,gundb,peerjs,trystero,webtorrent,hybrid}` | Six discovery plugins. |
| `@suaveplan/network-bootstrap` | Network bootstrap and initialisation. |
| `@suaveplan/network-quality` | Network quality monitoring. |
| `@suaveplan/network-observability` | Application monitoring. |
| `@suaveplan/network-assignment` | Role/resource assignment. |
| `@suaveplan/network-standby-transport` | Pre-emptive WebRTC standby transport. |

The "older naming" rows reflect a 2025-era split where each subsystem lived in its own package; the newer `network-plugin-*` naming is the genesis plugin-architecture form. Some of these will be **archived without a port** (`network-protocol`, `network-registry`, `network-webrtc`) because their content is already in the genesis equivalents. Verify before porting.

## Planned — new on `genesis` (the `network-suite` 21 plugins)

The full set of plugins from `network-suite` ([proposal](../../openspec/changes/network-suite/proposal.md)). Already-shipped subset is omitted; the remaining are:

| Package | Spec | Notes |
| --- | --- | --- |
| `@suaveplan/network-plugin-transport-manager` | NET-23..26, 46, 60, 123..124 | Multi-transport orchestration. |
| `@suaveplan/network-plugin-content-delivery` | NET-35..36 | Mesh-wide chunk redundancy. The drive-mesh consumer side. |
| `@suaveplan/network-plugin-audit-mesh` | NET-37..39 | Signed append-only logs. |
| `@suaveplan/network-plugin-relay` | NET-40, 61..70 | Cross-mesh forwarding. |
| `@suaveplan/network-plugin-assignment` | NET-71..77 | Peer→mesh assignment. |
| `@suaveplan/network-plugin-partition` | NET-78..83 | Partition detection + merge. |
| `@suaveplan/network-plugin-circuit-breaker` | NET-84..90 | Per-path breaker. |
| `@suaveplan/network-plugin-qos` | NET-91..98 | QoS classes + quotas. |
| `@suaveplan/network-plugin-migration` | NET-99..105 | 8-step peer migration. |
| `@suaveplan/network-plugin-auth` | NET-106..112 | Mesh + capability tokens, cross-mesh trust. |
| `@suaveplan/network-plugin-server-bridge` | NET-31..34, 56 | Server WebSocket bridge + 4 hosting models + offline mode. |
| `@suaveplan/network-plugin-session` | NET-18..22 | Session trees, nested hierarchies, per-session election, capacity. |
| `@suaveplan/network-plugin-crypto-messages` | NET-27..30, 47..48 | Ed25519 message signing. Plugin security verifier. Tier policies. |
| `@suaveplan/network-plugin-middleware` | NET-41 | Priority middleware pipeline. |
| `@suaveplan/network-plugin-state` | NET-42 | Versioned path-based state. |
| `@suaveplan/network-plugin-monitor` | NET-44 | OTel-compatible metrics + tracing. |
| `@suaveplan/network-plugin-simulation` | NET-43 | Deterministic virtual mesh + scenarios. |
| `@suaveplan/network-plugin-governance` enhancements | NET-118..119 | HostSelector with HostHistory (some shipped). |
| `@suaveplan/network-plugin-topology` enhancements | NET-49..52, 120..122 | Adaptive tier depth, partition handling, geo, battery, message pool. |

`network-suite/REVIEW-GAPS.md` lists 10 cross-cutting gaps that the per-plugin proposals address. The package-name collision (`enterprise-network` vs `network-core`) was resolved by renaming `enterprise-network` to `network-client`.

## Pending changes to consolidate (cleanup work)

There are a number of `enterprise-network-*` and `enterprise-browser-network-*` change folders that pre-date the `network-suite` reorganisation. Most are now subsumed:

| Folder | Status |
| --- | --- |
| `enterprise-network` | Rename to `network-client`; subset of features now in `network-suite`. |
| `enterprise-network-bootstrap` | Subsumed by `network-core` `BootstrapOptions`. |
| `enterprise-network-failover` | Subsumed by `network-plugin-failover` (already shipped). |
| `enterprise-network-governance` | Subsumed by `network-plugin-governance` (already shipped). |
| `enterprise-network-protocol` | Subsumed by `network-plugin-protocol` (already shipped). |
| `enterprise-network-registry` | Subsumed by `network-plugin-registry` (already shipped). |
| `enterprise-network-quality` | To become `network-plugin-monitor`. |
| `enterprise-network-observability` | To become `network-plugin-monitor`. |
| `enterprise-network-rename` | A no-code change to rename `enterprise-network` → `network-client`. |
| `enterprise-network-assignment` | To become `network-plugin-assignment`. |
| `enterprise-network-standby-transport` | To become `network-plugin-transport-manager`'s standby/preemptive feature. |
| `enterprise-network-testing` | Already shipped as `@suaveplan/network-testing`. |
| `enterprise-network-transport-websockets` | Already shipped as `@suaveplan/network-transport-websockets`. |
| `enterprise-browser-network-*` | All to be consolidated under the discovery plugins or `network-transport-webrtc`. |

These folders should be reviewed, archived, or rewritten to point at the canonical `network-suite` proposals. They are clutter, not architecture.

## Critical-path order (network)

1. **Land the `enterprise-types-cross-cutting` archive** (shared with drive prerequisite).
2. **Land `network-suite` REVIEW-GAPS resolutions** (no code; just spec consolidation). Includes the rename `enterprise-network` → `network-client` and archive of the duplicate `enterprise-network-*` folders.
3. **Implement `network-plugin-crypto-messages`** — message signing is foundational for everything else.
4. **Implement `network-plugin-transport-manager`** — multi-transport orchestration. Existing webrtc + websockets transports plug in.
5. **Implement `network-plugin-session`** — sessions are the unit of group membership.
6. **Implement `network-plugin-server-bridge`** — enables `SERVER_TO_CLIENT_FAILOVER` model. Brings hosting-model selection into the mesh.
7. **Implement `network-plugin-auth`** — token issuance + cross-mesh trust.
8. **Implement `network-plugin-relay`** — cross-mesh hops.
9. **Implement `network-plugin-content-delivery`** — drive's bus consumer.
10. **Implement `network-plugin-audit-mesh`** — signed logs.
11. **Implement `network-plugin-partition` + `network-plugin-circuit-breaker` + `network-plugin-qos` + `network-plugin-migration`**. Resilience tier.
12. **Implement `network-plugin-state`, `network-plugin-monitor`, `network-plugin-simulation`, `network-plugin-middleware`**. Operational tier.
13. **Port the discovery plugins** in any order — they feed `network-plugin-registry`.

Steps 3–4 are blocking; the rest can parallelise within their tier.

## Test debt to inherit / avoid

The `docs/old-network-planning/` folder has several files documenting real test-isolation bugs in the main-branch network code: shared `MemoryTransport._instances`, singleton `TimerController`, real `setTimeout` in time-sensitive tests, voting history not cleared between tests. The genesis fix is structural:

- `MemoryTransport` from `@suaveplan/network-testing` is per-test (no static registry).
- `FakeClock` from `@suaveplan/testing` is the only timer source.
- Each `NetworkNode` is fresh per test.
- All integration tests use `@suaveplan/testing-integration` fixtures (parallel-start, reverse-stop, idempotent teardown).

Don't re-import the old test patterns when porting. Use the genesis testing infrastructure.

## Related cross-cutting work

- `enterprise-streams-redesign` — `BaseTransform`, `CryptoTransform`, `BaseDuplexStream`, `NetworkStreamImpl`. Required for `network-plugin-protocol`'s pipeline (CryptoTransform/compressStream) and for `drive-plugin-chunks`'s real streaming AEAD.
- `enterprise-streams-chunk-queue` — bounded backpressure-aware `ChunkQueue` bridging sync producers and async WHATWG consumers.
- `enterprise-streams-metadata` — pass-through `TransformStream` extracting MIME/EXIF/audio metadata via side-channel `metadata: Promise<ExtractedMetadata>`. Drive `metadata` plugin consumes this.