Initial Commit
This commit is contained in:
@@ -0,0 +1,98 @@
|
||||
# OpenSpec Change: network-discovery-hybrid
|
||||
|
||||
- **Change ID**: network-discovery-hybrid
|
||||
- **Package**: `@suaveplan/network-discovery-hybrid`
|
||||
- **Category**: browser
|
||||
- **Target path**: `packages/network/network-discovery-hybrid`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-05-11
|
||||
- **Parent**: `network-transport-family` (2026-05-11) — Wave 2 (last)
|
||||
- **Migration source**: `../suaveplan/packages/browser/network-discovery-hybrid` + `../suaveplan/enterprise/network-discovery-hybrid.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Migrate `@suaveplan/network-discovery-hybrid` as the multi-strategy orchestrator that composes any subset of the other five Wave-2 discovery strategies (`peerjs`, `crdt`, `trystero`, `webtorrent`, `gundb`) into a single `HybridDiscoveryManager` with priority-based peer selection, per-strategy health tracking, automatic fallback when a strategy degrades, de-duplicated peer sets, and unified lifecycle. **Last package of Wave 2** because it has hard peer-deps on the other five.
|
||||
|
||||
---
|
||||
|
||||
## Why this is last in Wave 2
|
||||
|
||||
`HybridDiscoveryManager` cannot be meaningfully tested without at least two concrete strategies registered. Landing it after all five sibling packages means integration tests run against the real implementations rather than mocks (which AGENTS.md §0a explicitly bans).
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit
|
||||
|
||||
Upstream source layout (`../suaveplan/packages/browser/network-discovery-hybrid/src/`):
|
||||
|
||||
- `hybrid-discovery-manager.ts` (217 L) — top-level orchestrator
|
||||
- `strategy-manager.ts` (250 L) — health + priority bookkeeping
|
||||
- `types.ts` (258 L)
|
||||
- `lifecycle.ts` (164 L) — start/stop + transitions
|
||||
- `peer-tracker.ts` (145 L) — deduped peer set with sources
|
||||
- `strategy-loader.ts` — dynamic strategy loading
|
||||
- `__mocks__/strategy-mock.ts` ❌ — direct CLAUDE.md no-mocks violation
|
||||
|
||||
Upstream coverage: 4 test files (config-advanced, config, integration, runtime). React story without React dep.
|
||||
|
||||
---
|
||||
|
||||
## Parity Checklist
|
||||
|
||||
| Capability | Upstream | Migrated | Notes |
|
||||
|---|---|---|---|
|
||||
| `HybridDiscoveryManager` composer | ✅ | ✅ | |
|
||||
| Priority-based peer selection | ✅ | ✅ | |
|
||||
| Per-strategy `StrategyHealth` tracking | ✅ | ✅ | |
|
||||
| Automatic fallback on degradation | ✅ | ✅ | |
|
||||
| De-duplicated peer set with `PeerSource` provenance | ✅ | ✅ | |
|
||||
| Unified lifecycle (start/stop) | ✅ | ✅ | |
|
||||
| Dynamic strategy loading | ✅ | ✅ | |
|
||||
| `__mocks__/strategy-mock.ts` | ❌ (violates no-mocks rule) | 🚫 | DROPPED. Replaced with a real in-package `TestStrategy` fixture that implements `DiscoveryStrategy` deterministically — no `vi.mock` / `jest.mock`. |
|
||||
| `: any` usage in mocks | ❌ | 🚫 | Eliminated as a consequence of the above. |
|
||||
| Optional peer-deps on 5 siblings | ✅ | ✅ | `peerDependenciesMeta.{...}.optional: true` per upstream. |
|
||||
| Structured errors | 🚫 | ⬆️ | `defineCodes("NET_DISC_HYBRID", [...])`: `NO_STRATEGIES`, `ALL_STRATEGIES_DEGRADED`, `STRATEGY_LOAD_FAILED`, `DUPLICATE_STRATEGY`, `INVALID_OPTIONS`. |
|
||||
| Zod boundary validation | 🚫 | ⬆️ | `HybridDiscoveryConfig`, `StrategyConfig`, `StrategyPriority`. |
|
||||
| OTel instrumentation | 🚫 | ⬆️ | Counter `hybrid.peer_sources_total{strategy}`, histogram `hybrid.strategy_health_score{strategy}`, gauge `hybrid.active_strategies`. |
|
||||
| AbortSignal | 🚫 | ⬆️ | Threaded through every async path. |
|
||||
| `export *` barrels | check | ⬆️ | Convert to explicit named exports per §6a. |
|
||||
| Test-runner imports | direct vitest | ⬆️ | Rewrite to `@suaveplan/testing/runner` per §7. |
|
||||
| 100% test coverage | 🚫 | ⬆️ | Bring to 100/100/100/100 — integration test uses real Wave-2 siblings. |
|
||||
| React Storybook story | ✅ (no declared dep) | 🚫 | Dropped — out of scope for headless discovery package. |
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
- `@suaveplan/network` ✅
|
||||
- `@suaveplan/network-bootstrap` ⬅ Wave 1
|
||||
- `@suaveplan/service-discovery` ⬅ Wave 1
|
||||
- `@suaveplan/network-discovery-peerjs` ⬅ Wave 2 (peer-dep, optional)
|
||||
- `@suaveplan/network-discovery-crdt` ⬅ Wave 2 (peer-dep, optional)
|
||||
- `@suaveplan/network-discovery-trystero` ⬅ Wave 2 (peer-dep, optional)
|
||||
- `@suaveplan/network-discovery-webtorrent` ⬅ Wave 2 (peer-dep, optional)
|
||||
- `@suaveplan/network-discovery-gundb` ⬅ Wave 2 (peer-dep, optional)
|
||||
- `@suaveplan/types`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/timing` ✅
|
||||
- `@suaveplan/testing` ✅
|
||||
|
||||
**Blocking note.** Implementation MUST wait until all five sibling discovery strategies are shipped on genesis (per AGENTS.md §0b — pending dependencies must be migrated first). This proposal is approved but cannot start.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance gate
|
||||
|
||||
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-hybrid` green.
|
||||
2. `bunx turbo test:coverage --filter=@suaveplan/network-discovery-hybrid` 100/100/100/100.
|
||||
3. `bun run docs:check` green.
|
||||
4. `STATUS.md` row flipped.
|
||||
5. Integration test: register all five sibling strategies in a `HybridDiscoveryManager`, verify peer dedup, simulate strategy degradation, observe fallback. **No mocks** — the test uses real strategies against real (loopback) signaling.
|
||||
6. Spec: `openspec/specs/network-discovery-hybrid/spec.md` with `## ADDED Requirements`.
|
||||
|
||||
---
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Adding NEW concrete strategies beyond the Wave-2 set (future Wave-9 work).
|
||||
- Cross-network federation across multiple hybrid managers (separate proposal).
|
||||
@@ -0,0 +1,64 @@
|
||||
# Tasks — network-discovery-hybrid
|
||||
|
||||
## Phase 1: Scaffold
|
||||
|
||||
- [ ] 1.1 Create `packages/network/network-discovery-hybrid/` with feature-module layout.
|
||||
- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports.
|
||||
- [ ] 1.3 Declare optional peer-deps on the five sibling discovery packages with `peerDependenciesMeta.{...}.optional: true`.
|
||||
- [ ] 1.4 Test config via `createTestConfig()`; `tests/dep-graph.test.ts`.
|
||||
|
||||
## Phase 2: Types + errors
|
||||
|
||||
- [ ] 2.1 Port `types.ts` → `src/types/types.ts` + sibling `.md`.
|
||||
- [ ] 2.2 `defineCodes("NET_DISC_HYBRID", [...])` per parity checklist.
|
||||
- [ ] 2.3 Zod schemas for `HybridDiscoveryConfig`, `StrategyConfig`, `StrategyPriority`.
|
||||
|
||||
## Phase 3: Core orchestrator
|
||||
|
||||
- [ ] 3.1 Port `HybridDiscoveryManager` orchestrator.
|
||||
- [ ] 3.2 Port `StrategyManager` (health + priority).
|
||||
- [ ] 3.3 Port `Lifecycle` start/stop FSM.
|
||||
- [ ] 3.4 Port `PeerTracker` deduped peer set with `PeerSource`.
|
||||
- [ ] 3.5 Port `StrategyLoader` dynamic loader (resolves optional peer-deps lazily).
|
||||
|
||||
## Phase 4: Banned-mock removal
|
||||
|
||||
- [ ] 4.1 DELETE `__mocks__/strategy-mock.ts` — do not port.
|
||||
- [ ] 4.2 Author a real in-package `TestStrategy` fixture implementing `DiscoveryStrategy` deterministically (no `vi.mock` / `jest.mock`).
|
||||
- [ ] 4.3 Verify zero `: any` usage in production source.
|
||||
|
||||
## Phase 5: Observability
|
||||
|
||||
- [ ] 5.1 Counter `hybrid.peer_sources_total{strategy}`.
|
||||
- [ ] 5.2 Histogram `hybrid.strategy_health_score{strategy}`.
|
||||
- [ ] 5.3 Gauge `hybrid.active_strategies`.
|
||||
|
||||
## Phase 6: Integration (REAL strategies — no mocks)
|
||||
|
||||
- [ ] 6.1 Integration test: register all five Wave-2 siblings, verify peer dedup with `PeerSource` correctness.
|
||||
- [ ] 6.2 Integration test: simulate degradation of one strategy (cut signaling), verify priority-based fallback to next-healthiest.
|
||||
- [ ] 6.3 Integration test: lifecycle (start all → stop one → restart) idempotency.
|
||||
|
||||
## Phase 7: Tests + docs
|
||||
|
||||
- [ ] 7.1 Unit tests via `@suaveplan/testing/runner`.
|
||||
- [ ] 7.2 fast-check property tests: peer dedup commutativity, priority-order stability.
|
||||
- [ ] 7.3 100/100/100/100 coverage gate.
|
||||
- [ ] 7.4 Sibling `.md` per `.ts` impl file.
|
||||
- [ ] 7.5 Root `README.md` with basic + advanced examples.
|
||||
|
||||
## Phase 8: Verification
|
||||
|
||||
- [ ] 8.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-hybrid` green.
|
||||
- [ ] 8.2 `bunx turbo test:coverage --filter=@suaveplan/network-discovery-hybrid` 100/100/100/100.
|
||||
- [ ] 8.3 `bun run docs:check --filter=@suaveplan/network-discovery-hybrid` green.
|
||||
- [ ] 8.4 `MANIFEST.md` regen.
|
||||
- [ ] 8.5 `STATUS.md` row flipped.
|
||||
|
||||
## Pre-archive checklist
|
||||
|
||||
- [ ] Row 1 — Phase 8 green.
|
||||
- [ ] Row 2 — Parity 🚫 list empty (mocks/stories both legitimately dropped with justification).
|
||||
- [ ] Row 3 — `openspec/specs/network-discovery-hybrid/spec.md` written.
|
||||
- [ ] Row 4 — Integration test against all five real siblings passes.
|
||||
- [ ] Row 5 — Folder archived.
|
||||
Reference in New Issue
Block a user