Initial Commit

openspec/archive/2026-05-11-network-discovery-crdt/proposal.md

@@ -0,0 +1,81 @@
+# 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).

openspec/archive/2026-05-11-network-discovery-crdt/tasks.md

@@ -0,0 +1,56 @@
+# Tasks — network-discovery-crdt
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/network-discovery-crdt/` with standard feature-module layout.
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports per module.
+- [ ] 1.3 Test config via `createTestConfig()`.
+- [ ] 1.4 `tests/dep-graph.test.ts`.
+
+## Phase 2: Types + errors
+
+- [ ] 2.1 Port public types into `src/types/` + sibling `.md`.
+- [ ] 2.2 `defineCodes` registry per parity checklist.
+- [ ] 2.3 Zod schemas for every public option struct.
+
+## Phase 3: Core strategy
+
+- [ ] 3.1 Port the `DiscoveryStrategy` implementation module(s) listed in the audit.
+- [ ] 3.2 Replace ad-hoc retry/event utilities with `@suaveplan/retry` + `@suaveplan/events`.
+- [ ] 3.3 Inject `Clock` and `Rng` via `@suaveplan/types` contracts.
+- [ ] 3.4 Thread `AbortSignal` through every async path.
+
+## Phase 4: Observability
+
+- [ ] 4.1 OTel spans for strategy lifecycle.
+- [ ] 4.2 Counters for discovered peers / failures.
+- [ ] 4.3 Histograms for handshake / signaling duration.
+
+## Phase 5: Integration
+
+- [ ] 5.1 Cross-package integration test with `@suaveplan/network-bootstrap`: register this strategy in the discovery chain, run a node, observe `peer:found` events.
+- [ ] 5.2 Optional: register discovered peers into `@suaveplan/service-discovery`.
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests per feature module via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests where applicable (peer dedup, retry idempotency).
+- [ ] 6.3 100/100/100/100 coverage gate.
+- [ ] 6.4 Sibling `.md` doc per `.ts` impl file.
+- [ ] 6.5 Root `README.md` with basic + advanced examples.
+
+## Phase 7: Verification
+
+- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-crdt` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/network-discovery-crdt` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check --filter=@suaveplan/network-discovery-crdt` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped from `–` to `✅`.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — Parity 🚫 list empty.
+- [ ] Row 3 — `openspec/specs/network-discovery-crdt/spec.md` written.
+- [ ] Row 4 — `network-bootstrap` integration test passes.
+- [ ] Row 5 — Folder archived.