Initial Commit

openspec/archive/2026-05-11-service-discovery/proposal.md

@@ -0,0 +1,81 @@
+# OpenSpec Change: service-discovery
+
+- **Change ID**: service-discovery
+- **Package**: `@suaveplan/service-discovery`
+- **Category**: universal
+- **Target path**: `packages/network/service-discovery`
+- **Status**: PROPOSED
+- **Date**: 2026-05-11
+- **Parent**: `network-transport-family` (2026-05-11) — Wave 1
+- **Migration source**: `../suaveplan/packages/universal/service-discovery` + `../suaveplan/enterprise/service-discovery.md`
+
+---
+
+## Summary
+
+Migrate `@suaveplan/service-discovery` into genesis as a universal-tier helper library backing every `network-discovery-*` plugin (Wave 2). Upstream ships at 97.76% coverage with a `ServiceRegistry` and supporting types. The migration ports the surface, hardens against genesis primitives, and provides the shared `ServiceDescriptor` / `ServiceRegistry` contract that all six Wave-2 discovery plugins consume.
+
+---
+
+## Why this is needed
+
+Every concrete discovery plugin (`crdt`, `peerjs`, `trystero`, `webtorrent`, `gundb`, `hybrid`) needs the same primitives: register a service, query for services by name/tag/region, watch for service-set changes, expire stale entries. Without a shared `service-discovery` library, each plugin would re-implement this differently and the `hybrid` orchestrator would have no canonical merge semantics. Landing `service-discovery` in Wave 1 keeps Wave 2 small.
+
+---
+
+## Current-state audit
+
+Upstream surface (`../suaveplan/packages/universal/service-discovery/src/`):
+
+- `service-registry.ts` — in-memory `ServiceRegistry` with register/deregister/query/watch
+- `types.ts` — `ServiceDescriptor`, `ServiceQuery`, `RegistryEvent`
+- `service-registry.test.ts` + `service-registry.md`
+
+Upstream coverage: 97.76% statement, no E2E. No structured errors, no Zod, no OTel.
+
+---
+
+## Parity Checklist
+
+| Capability | Upstream | Migrated | Notes |
+|---|---|---|---|
+| `ServiceDescriptor` type | ✅ | ✅ | Considered for `@suaveplan/types` promotion if Wave 2 plugins import directly; default keep local. |
+| `ServiceRegistry` register/deregister | ✅ | ✅ | |
+| `ServiceQuery` by name/tag/region | ✅ | ✅ | |
+| `watch(query)` AsyncIterable | ✅ | ✅ | `AbortSignal` honoured on iterator. |
+| TTL + stale-entry expiry | ✅ | ✅ | Injectable `Clock` per AGENTS.md. |
+| Persistent backing | 🚫 | ⬆️ | Opt-in `@suaveplan/storage` `AbstractStorage` adapter for cross-restart persistence. |
+| Structured errors | 🚫 | ⬆️ | `defineCodes("SVC_DISC", [...])`: `DUPLICATE_REGISTRATION`, `QUERY_INVALID`, `REGISTRY_FULL`, `INVALID_OPTIONS`. |
+| Zod boundary validation | 🚫 | ⬆️ | Every public option struct + `ServiceDescriptor`. |
+| OTel instrumentation | 🚫 | ⬆️ | Counters (`svc_disc.registrations_total{outcome}`, `:queries_total`), histogram (`svc_disc.query_duration_ms`), gauge (`svc_disc.active_services`). |
+| `NetworkBus` event integration | 🚫 | ⬆️ | Opt-in: emit `service:registered`/`:deregistered`/`:expired` topics when a bus is provided. |
+| AbortSignal support | 🚫 | ⬆️ | Threaded everywhere. |
+| `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 | 🚫 (97.76%) | ⬆️ | Bring to 100/100/100/100. |
+| Property tests | 🚫 | ⬆️ | fast-check property suite on TTL expiry monotonicity + query determinism. |
+
+---
+
+## Available workspace deps on genesis
+
+- `@suaveplan/types` ✅
+- `@suaveplan/error` ✅
+- `@suaveplan/events` ✅ (optional bus integration)
+- `@suaveplan/storage` ✅ (optional persistence)
+- `@suaveplan/testing` ✅
+
+No blockers.
+
+---
+
+## Acceptance gate
+
+Identical to `network-bootstrap` (lint+typecheck+test green, 100% coverage, `docs:check` green, `STATUS.md` flipped, dep-graph cycle-free).
+
+---
+
+## Out of scope
+
+- Concrete transport-specific discovery (Wave 2).
+- Cross-cluster service-mesh federation (future package; not in upstream).

openspec/archive/2026-05-11-service-discovery/tasks.md

@@ -0,0 +1,54 @@
+# Tasks — service-discovery
+
+## Phase 1: Scaffold
+
+- [ ] 1.1 Create `packages/network/service-discovery/` with standard package layout.
+- [ ] 1.2 `package.json` at `0.1.0`, `"sideEffects": false`, subpath exports.
+- [ ] 1.3 Test config via `createTestConfig()`.
+- [ ] 1.4 `tests/dep-graph.test.ts`.
+
+## Phase 2: Types + errors
+
+- [ ] 2.1 Port `types.ts` → `src/types/types.ts` + sibling `.md`.
+- [ ] 2.2 `defineCodes("SVC_DISC", [...])`: `DUPLICATE_REGISTRATION`, `QUERY_INVALID`, `REGISTRY_FULL`, `INVALID_OPTIONS`.
+- [ ] 2.3 Zod schemas for `ServiceDescriptor`, `ServiceQuery`, options.
+
+## Phase 3: Core registry
+
+- [ ] 3.1 Port `ServiceRegistry` register/deregister/query.
+- [ ] 3.2 `watch(query)` AsyncIterable with AbortSignal-aware termination.
+- [ ] 3.3 TTL + stale-entry expiry over injectable `Clock`.
+
+## Phase 4: Adapters
+
+- [ ] 4.1 Optional persistent backing via `@suaveplan/storage` `AbstractStorage`.
+- [ ] 4.2 Optional `NetworkBus` integration emitting `service:registered`/`:deregistered`/`:expired`.
+
+## Phase 5: Observability
+
+- [ ] 5.1 Counters (`svc_disc.registrations_total{outcome}`, `svc_disc.queries_total`).
+- [ ] 5.2 Histogram (`svc_disc.query_duration_ms`).
+- [ ] 5.3 Gauge (`svc_disc.active_services`).
+
+## Phase 6: Tests + docs
+
+- [ ] 6.1 Unit tests per feature module via `@suaveplan/testing/runner`.
+- [ ] 6.2 fast-check property tests: TTL monotonicity, query determinism.
+- [ ] 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/service-discovery` green.
+- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/service-discovery` 100/100/100/100.
+- [ ] 7.3 `bun run docs:check --filter=@suaveplan/service-discovery` green.
+- [ ] 7.4 `MANIFEST.md` regen.
+- [ ] 7.5 `STATUS.md` row flipped.
+
+## Pre-archive checklist
+
+- [ ] Row 1 — Phase 7 green.
+- [ ] Row 2 — Parity 🚫 list empty (or each row justified per AGENTS.md §0a).
+- [ ] Row 3 — `openspec/specs/service-discovery/spec.md` written.
+- [ ] Row 4 — Folder archived.