SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Commit

Browse Source
This commit is contained in:
admin
2026-05-27 23:29:53 +01:00
commit fbc70f96e6
10000 changed files with 1102152 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
openspec/archive/2026-05-12-network-transport-family/proposal.md Normal file
View File

@@ -0,0 +1,142 @@
# OpenSpec Change: network-transport-family
- **Change ID**: network-transport-family
- **Type**: naming convention + restructure
- **Status**: PROPOSED
- **Date**: 2026-05-11
- **Related**: `network-suite` (2026-04-29), `enterprise-network-rename` (2026-05-01)
---
## Summary
Introduce a dedicated `@suaveplan/network-transport-*` package family for concrete `Transport` implementations consumed by `@suaveplan/network-plugin-transport-manager`. Reclassifies one shipped plugin, retires one pre-OpenSpec orphan, and net-adds seven transport packages currently listed under `–` (unmigrated) in `STATUS.md`. Reserves `network-plugin-*` for **cross-cutting orchestration plugins** (governance, failover, qos, audit-mesh, …) and reserves `network-discovery-*` for **peer rendezvous strategies**.
This is a **naming + boundary** change. No new transport functionality is implemented in this proposal — each concrete transport gets its own follow-up migration change with the standard parity checklist.
---
## Why
Today the `@suaveplan/network-plugin-*` namespace conflates two categorically different things:
1. **Wire-level `Transport` implementations** — `webrtc`, `websockets`, `hyperswarm`, `libp2p`, `trystero`, `gundb`, `peerjs`, `webtorrent`. These all implement the same structural `Transport` contract (`connect`/`disconnect`/`send`/`onMessage`/`onPeerEvent`/`getConnectedPeers`/`close`) defined in `@suaveplan/network` and are orchestrated as a pool by `network-plugin-transport-manager` ✅.
2. **Cross-cutting orchestration plugins** — `governance`, `failover`, `qos`, `partition`, `circuit-breaker`, `audit-mesh`, `server-bridge`, `content-delivery`, `migration`, `auth`, `crypto-messages`, `state`, `relay`, `assignment`, `protocol`, `registry`, `session`, `topology`, `monitor`, `simulation`, `intra-relay`, `devtools`, `middleware`. These hook into the `NetworkPlugin` lifecycle but do not move bytes on the wire.
Collapsing both into `network-plugin-*` hides this distinction. The package list (35 plugins per `MANIFEST.md`) is impossible to scan for "what transports exist?" without inspecting each `package.json`. Discovery tooling, transport-manager configuration, and downstream documentation all suffer.
Three further problems:
- **Drive already follows this convention.** `@suaveplan/drive-transport-https` ✅ ships today. The network side should match.
- **The `–` backlog is full of unnamed transports.** `STATUS.md` lists `network-hyperswarm`, `network-libp2p`, `network-libp2p-server`, `network-standby-transport`, `network-webrtc`, `network-websockets` as pending. Half of these are transports, half are something else; the bare names give no clue.
- **Pre-OpenSpec orphans pollute the namespace.** `@suaveplan/network-{topology,failover,governance}` shipped before OpenSpec was set up properly in genesis and were already superseded by their `network-plugin-*` counterparts. (Deleted on this branch — see §3.)
A first-class `network-transport-*` family solves all three: clear contract boundary, scannable inventory, parallel with `drive-transport-*` / `network-discovery-*`, and a natural home for the pending wire-level packages.
---
## What changes
### 1. Renames (shipped → renamed)
| Before | After | Reason |
|---|---|---|
| `@suaveplan/network-plugin-webrtc` ✅ | `@suaveplan/network-transport-webrtc` | Concrete `Transport` impl, not an orchestration plugin. |
Path move: `packages/network/network-plugin-webrtc/` → `packages/network/network-transport-webrtc/`.
The package continues to expose a `NetworkPlugin` wrapper for backward compatibility — the `NetworkPlugin` interface is how transports register with `NetworkNode`. The rename clarifies *role*, not *contract*.
### 2. Promotions (bare → transport)
| Before | After | Reason |
|---|---|---|
| `@suaveplan/network-websockets` ✅ (bare, pre-OpenSpec) | `@suaveplan/network-transport-websockets` | Pre-OpenSpec migration; folds into the transport family with proper plugin wrapper. |
Path move: `packages/network/network-websockets/` → `packages/network/network-transport-websockets/`.
### 3. Already-deleted orphans (no action — recorded for traceability)
These three packages were migrated from suaveplan before OpenSpec was set up properly in this monorepo and were never referenced by any consumer. They were deleted on the `genesis` branch on 2026-05-11. Their canonical `network-plugin-*` replacements are already shipped.
| Deleted | Canonical replacement |
|---|---|
| `@suaveplan/network-topology` (no consumers) | `@suaveplan/network-plugin-topology` ✅ |
| `@suaveplan/network-failover` (no consumers) | `@suaveplan/network-plugin-failover` ✅ |
| `@suaveplan/network-governance` (no consumers) | `@suaveplan/network-plugin-governance` ✅ |
### 4. New transport packages (status `–` → scoped, implementation deferred)
Each of these gets a stub `package.json` at `0.1.0`, an `openspec/changes/network-transport-<name>/proposal.md` with the standard migration parity checklist (per AGENTS.md §0a), and a `tasks.md`. Implementation is **out of scope for this proposal** — this change only reserves names + paths + spec slots.
| Package | Source mapping | Tier |
|---|---|---|
| `@suaveplan/network-transport-hyperswarm` | `../suaveplan/enterprise/network-hyperswarm.md` | server (Node-only) |
| `@suaveplan/network-transport-libp2p` | `../suaveplan/enterprise/network-libp2p.md` | universal |
| `@suaveplan/network-transport-trystero` | `../suaveplan/enterprise/network-trystero*.md` | browser |
| `@suaveplan/network-transport-gundb` | `../suaveplan/enterprise/network-gundb*.md` | universal |
| `@suaveplan/network-transport-peerjs` | `../suaveplan/enterprise/network-peerjs.md` (if present) | browser |
| `@suaveplan/network-transport-webtorrent` | `../suaveplan/enterprise/network-webtorrent.md` (if present) | browser |
| `@suaveplan/network-transport-standby` | `../suaveplan/enterprise/network-standby-transport.md` | universal |
### 5. Drive transport — left in place
`@suaveplan/drive-transport-https` stays where it is. The transport contract there is `TransportLike<MessageEnvelope>` over a drive-mesh wire, not the `Transport` contract from `@suaveplan/network`. Confusable name, different interface. A future change MAY revisit, but this proposal does not touch it.
### 6. Reserved namespaces (going forward)
| Prefix | Contract |
|---|---|
| `@suaveplan/network-transport-*` | Implements `Transport` from `@suaveplan/network`. Wire-level. Registers with `network-plugin-transport-manager`. |
| `@suaveplan/network-plugin-*` | Implements `NetworkPlugin` from `@suaveplan/network`. Cross-cutting orchestration. |
| `@suaveplan/network-discovery-*` | Implements peer-rendezvous strategy. Feeds peer identities into transports. |
| `@suaveplan/network-*` (bare) | Reserved for `@suaveplan/network` core + first-class utilities (`network-testing` ✅). Avoid for new packages — pick one of the three families above. |
---
## Parity Checklist
Not applicable. This is a naming + restructure change against genesis-shipped code, not a migration from upstream. The per-transport migrations in §4 each carry their own parity checklist when their proposals land.
---
## Consumer impact
### `@suaveplan/network-plugin-webrtc` rename
- `package.json` `name` change is a breaking import for any consumer importing from `@suaveplan/network-plugin-webrtc`. Search across genesis:
- `packages/network/network-plugin-transport-manager/` references via `workspace:^` — must update.
- `STATUS.md`, `MANIFEST.md`, `SUMMARY.md`, `docs/network/*` — regen.
- `openspec/specs/network-webrtc/` — fold delta and rename spec subject if the spec name is package-bound.
- No external (npm) consumers yet — all `@suaveplan/network-*` packages are at `0.1.0`, so the rename has zero release-side cost.
### `@suaveplan/network-websockets` promotion
- Same scope as above. No external consumers; rename in place; regen manifests.
### Backward compatibility
- No deprecation shims are required because every `@suaveplan/network-*` package is still pre-1.0 (`0.1.0`). Per `CLAUDE.md` "Package Lifecycle": versions only bump at 1.0 graduation. No deprecation alias packages will be published.
---
## Verification approach
The change is complete when:
1. `packages/network/network-transport-webrtc/` exists; old path absent.
2. `packages/network/network-transport-websockets/` exists; old path absent.
3. Every internal `workspace:^` reference to the two renamed packages is updated.
4. `bunx turbo lint typecheck test --filter='@suaveplan/network*'` is green.
5. `bunx turbo test:coverage --filter='@suaveplan/network*'` remains at the pre-rename coverage baseline (no test regressions from the path move).
6. `bun scripts/folder-reorg/generate-manifest.ts` regenerates `MANIFEST.md` cleanly.
7. `STATUS.md`, `SUMMARY.md`, `CLAUDE.md` package listings reflect the new names.
8. Per-transport child proposals in §4 each exist with `proposal.md` + `tasks.md` (implementation deferred).
9. `openspec/specs/network-webrtc/` spec is renamed/refolded to match the new package name.
10. Root `bun run gate` is green.
---
## Source mapping
This change has no upstream source — it consolidates a naming convention against genesis shipped code. The per-transport child changes (§4) each map to upstream `../suaveplan/enterprise/network-*.md` audit documents.

56
openspec/archive/2026-05-12-network-transport-family/tasks.md Normal file
View File

@@ -0,0 +1,56 @@
# Tasks — network-transport-family
## Phase 1: Rename shipped plugins
- [ ] 1.1 Move `packages/network/network-plugin-webrtc/` → `packages/network/network-transport-webrtc/`.
- [ ] 1.2 Update `package.json` `"name"` → `@suaveplan/network-transport-webrtc`.
- [ ] 1.3 Update every internal `workspace:^` consumer (audit: `network-plugin-transport-manager`, any test fixture).
- [ ] 1.4 Rename `openspec/specs/network-webrtc/` if the spec subject is package-bound; otherwise fold a `## MODIFIED` delta noting the rename.
- [ ] 1.5 Verify: `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-webrtc` green.
## Phase 2: Promote pre-OpenSpec bare transport
- [ ] 2.1 Move `packages/network/network-websockets/` → `packages/network/network-transport-websockets/`.
- [ ] 2.2 Update `package.json` `"name"` → `@suaveplan/network-transport-websockets`.
- [x] 2.3 Audit `NetworkPlugin` wrapper. **Finding (2026-05-11)**: `network-transport-websockets` predates the `Transport` contract and exposes a client-server `WebSocketClient` rather than a peer transport. Wiring it as a `NetworkPlugin` requires a non-trivial refactor (per-peer connections, `getConnectedPeers()` aggregation, `transport:connected`/`disconnected` bus emission). Deferred to a dedicated child proposal `network-transport-websockets-plugin-adapter`.
- [ ] 2.4 Update every internal `workspace:^` consumer.
- [ ] 2.5 Fold `openspec/specs/network-websockets/` (if present) or write a fresh spec capturing the transport contract.
- [ ] 2.6 Verify: `bunx turbo lint typecheck test --filter=@suaveplan/network-transport-websockets` green.
## Phase 3: Reserve new transport namespaces (proposals only — no implementation)
For each transport, scaffold `openspec/changes/network-transport-<name>/` with `proposal.md` + `tasks.md` populated against `../suaveplan/enterprise/network-<name>.md` and the standard migration parity checklist. **No code authored in this phase.**
- [ ] 3.1 `network-transport-hyperswarm` proposal.
- [ ] 3.2 `network-transport-libp2p` proposal.
- [ ] 3.3 `network-transport-trystero` proposal.
- [ ] 3.4 `network-transport-gundb` proposal.
- [ ] 3.5 `network-transport-peerjs` proposal (skip if no upstream audit exists; record gap).
- [ ] 3.6 `network-transport-webtorrent` proposal (skip if no upstream audit exists; record gap).
- [ ] 3.7 `network-transport-standby` proposal.
## Phase 4: Docs + manifest regen
- [ ] 4.1 Run `bun scripts/folder-reorg/generate-manifest.ts`; confirm `MANIFEST.md` reflects new names.
- [ ] 4.2 Update `STATUS.md` rows for the two renamed packages (drop bare rows; add transport rows).
- [ ] 4.3 Update `SUMMARY.md` rows.
- [ ] 4.4 Update `CLAUDE.md` package listing (search for `network-plugin-webrtc` + `network-websockets`).
- [ ] 4.5 Update `docs/network/*` references.
## Phase 5: Conformance
- [ ] 5.1 `bunx turbo lint typecheck test --filter='@suaveplan/network*'` green.
- [ ] 5.2 `bunx turbo test:coverage --filter='@suaveplan/network*'` at or above pre-rename baseline.
- [ ] 5.3 `bun scripts/openspec-conformance.ts` (or repo-equivalent) green for every renamed package.
- [ ] 5.4 Root `bun run gate` green.
## Pre-archive checklist
- [ ] Row 1 — Verified by: Both renamed packages compile and test green.
- [ ] Row 2 — Verified by: No remaining `workspace:^` reference to `@suaveplan/network-plugin-webrtc` or `@suaveplan/network-websockets` anywhere in `packages/`.
- [ ] Row 3 — Verified by: `MANIFEST.md`, `STATUS.md`, `SUMMARY.md`, `CLAUDE.md` all reflect the new names.
- [ ] Row 4 — Verified by: All seven Phase 3 child proposals exist with parity checklists.
- [ ] Row 5 — Verified by: `openspec/specs/network-webrtc/` spec subject reflects the rename.
- [ ] Row 6 — Verified by: Root `bun run gate` is green.
- [ ] Row 7 — Verified by: This proposal folded into `openspec/specs/network/spec.md` (or sibling) under `## MODIFIED Requirements` recording the naming convention as load-bearing.
- [ ] Row 8 — Verified by: Folder moved to `openspec/archive/<yyyy-mm-dd>-network-transport-family/`.