82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# OpenSpec Change: network-discovery-crdt
|
||
|
||
- **Change ID**: network-discovery-crdt
|
||
- **Package**: `@suaveplan/network-discovery-crdt`
|
||
- **Category**: browser
|
||
- **Target path**: `packages/network/network-discovery-crdt`
|
||
- **Status**: PROPOSED
|
||
- **Date**: 2026-05-11
|
||
- **Parent**: `network-transport-family` (2026-05-11) — Wave 2
|
||
- **Migration source**: `../suaveplan/packages/browser/network-discovery-crdt` + `../suaveplan/enterprise/network-discovery-crdt.md`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Migrate `@suaveplan/network-discovery-crdt` as a browser-tier `DiscoveryStrategy` for `@suaveplan/network`. CRDT awareness layers (Yjs + Automerge) for eventually-consistent peer-metadata exchange. Two interchangeable provider backends behind a single `CRDTDiscovery` class.
|
||
|
||
---
|
||
|
||
## Current-state audit
|
||
|
||
Upstream source layout (`../suaveplan/packages/browser/network-discovery-crdt/src/`):
|
||
|
||
- `crdt-discovery.ts` (183 L) — orchestrator
|
||
- `crdt-state-manager.ts` (221 L)
|
||
- `crdt-peer-manager.ts` (155 L)
|
||
- `crdt-initializer.ts` (158 L) — bootstrap
|
||
- `crdt-intervals.ts` (105 L) — periodic reconciliation
|
||
- `automerge-discovery.ts` (216 L) — Automerge provider path
|
||
- Yjs provider modules (`yjs-discovery`, `yjs-awareness`, `yjs-sync`)
|
||
|
||
See `../suaveplan/enterprise/network-discovery-crdt.md` for full upstream surface inventory.
|
||
|
||
---
|
||
|
||
## Parity Checklist
|
||
|
||
| Capability | Upstream | Migrated | Notes |
|
||
|---|---|---|---|
|
||
| `DiscoveryStrategy` impl | ✅ | ✅ | |
|
||
| Yjs provider | ✅ | ✅ | y-webrtc signaling + awareness. |
|
||
| Automerge provider | ✅ | ✅ | @automerge/automerge-repo + broadcast-channel + websocket + IndexedDB adapters. |
|
||
| Provider abstraction | ✅ | ⬆️ | Tightened — Yjs/Automerge selection at construction time, no runtime swap.|
|
||
| Structured errors | 🚫 | ⬆️ | `defineCodes` registry with strategy-specific codes. |
|
||
| Zod boundary validation | 🚫 | ⬆️ | Every public option struct. |
|
||
| OTel instrumentation | 🚫 | ⬆️ | Spans + counters + histograms keyed by strategy. |
|
||
| AbortSignal | 🚫 | ⬆️ | Threaded through `start`/`stop`/`connect`. |
|
||
| `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. |
|
||
| Property tests | 🚫 | ⬆️ | fast-check property suite where applicable. |
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
- `@suaveplan/network` ✅
|
||
- `@suaveplan/network-bootstrap` ⬅ Wave 1
|
||
- `@suaveplan/service-discovery` ⬅ Wave 1
|
||
- `@suaveplan/types`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/timing` ✅
|
||
- `@suaveplan/testing` ✅
|
||
- External: `yjs, y-webrtc, @automerge/automerge-repo + adapters` — add to root catalog under `network-discovery`.
|
||
|
||
**Blocking note.** Wave 1 (`network-bootstrap`, `service-discovery`) must land first.
|
||
|
||
---
|
||
|
||
## Acceptance gate
|
||
|
||
1. `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-crdt` green.
|
||
2. `bunx turbo test:coverage --filter=@suaveplan/network-discovery-crdt` 100/100/100/100.
|
||
3. `bun run docs:check` green (sibling `.md` per `.ts`).
|
||
4. `STATUS.md` row flipped from `–` to `✅`.
|
||
5. `network-bootstrap` chain integration test demonstrates this strategy as a working entry.
|
||
|
||
---
|
||
|
||
## Out of scope
|
||
|
||
- Hosting / running any required relays or trackers (deployment concern).
|
||
- React Storybook stories — discovery is a universal/headless tier; UI lives in a dedicated devtools package (future).
|