Initial Commit

openspec/archive/2026-05-12-enterprise-network-registry/tasks.md

@@ -0,0 +1,95 @@
+# Tasks: enterprise-network-registry
+
+**Change ID**: enterprise-network-registry
+**Package**: `@suaveplan/network-registry`
+**Target path**: `universal/network/network-registry`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger`
+
+---
+
+## 1. Scaffold
+
+- [x] Create `universal/network/network-registry/` with `src/`, `tests/`, and all feature subdirectories.
+- [x] Write `package.json` at version `0.1.0`: `"sideEffects": false`, exports map, deps per `proposal.md`.
+- [x] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Types and error codes
+
+- [x] Define all public types in `src/types/common.ts`: `RegistryEntry`, `HealthStatus`, `RegistrationHandle`, `RegistryQuery`, `RegistryFilter`, `RegistryChangeHandler`, `RegistryChange`, `NetworkRegistryOptions`.
+- [x] Write `src/types/common.md` (≥200 words, simple + advanced examples).
+- [x] Define error codes in `src/error-codes.ts`.
+- [x] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
+
+---
+
+## 3. TTL manager (`src/core/ttl-manager/`)
+
+- [x] Implement `createTtlManager(clock)`:
+  - Tracks `expiresAt` per entry.
+  - `isExpired(entry)` — compare against `clock.now()`.
+  - `purge(entries)` — returns list of expired entry IDs.
+  - Runs GC on `gcIntervalMs` interval via injectable timer.
+- [x] Write `ttl-manager.test.ts` + `ttl-manager.md`.
+
+---
+
+## 4. Query engine (`src/core/query-engine/`)
+
+- [x] Implement `evaluateQuery(entry: RegistryEntry, query: RegistryQuery): boolean`:
+  - `type`: match entry type (array = OR, string = exact).
+  - `capabilities` (AND): entry must have ALL capabilities.
+  - `anyCapabilities` (OR): entry must have AT LEAST ONE.
+  - `tags`: all key/value pairs must match.
+  - `region`: exact match.
+  - `healthyOnly`: entry.health.healthy must be true.
+- [x] Implement `runQuery(entries: RegistryEntry[], query: RegistryQuery): RegistryEntry[]`:
+  - Filter via `evaluateQuery`, sort by latency (lowest first), apply `limit`.
+- [x] Write `query-engine.test.ts` (≤500 lines): each filter type, AND/OR capabilities, limit.
+- [x] Write `query-engine.md` (≥200 words).
+
+---
+
+## 5. Network registry (`src/core/registry/`)
+
+- [x] Implement `createNetworkRegistry(options?)`:
+  - Validates options with Zod.
+  - Stores entries in `Map<string, RegistryEntry>`.
+  - Wires TTL manager for expiry.
+  - Stores subscriptions as `Array<{ query: RegistryQuery; handler: RegistryChangeHandler }>`.
+- [x] Implement `registry.register(entry)`:
+  - Validate with Zod; throw `REGISTRY_INVALID_ENTRY` on schema failure.
+  - Throw `REGISTRY_DUPLICATE_ID` if already registered.
+  - Check `maxEntries`; throw `REGISTRY_CAPACITY_EXCEEDED` if at limit.
+  - Compute `expiresAt = clock.now() + (entry.ttlMs ?? options.ttlDefaultMs)`.
+  - Return `RegistrationHandle` with `renew()` and `deregister()`.
+  - Emit event-bus `registry.registered` event; notify matching subscriptions.
+  - OTel: counter `registry.register_total`.
+- [x] Implement `registry.deregister(id)` — remove; emit `registry.deregistered`; notify subscriptions.
+- [x] Implement `registry.lookup(query)` — delegates to query engine; OTel counter `registry.lookup_total`, histogram `registry.lookup_results`.
+- [x] Implement `registry.get(id)` — direct lookup; throws `REGISTRY_EXPIRED` if TTL elapsed.
+- [x] Implement `registry.list(filter?)` — returns all non-expired entries matching optional filter.
+- [x] Implement `registry.updateHealth(id, status)` — updates health; emits `health-changed`.
+- [x] Implement `registry.subscribe(query, handler)` — returns unsubscribe.
+- [x] Implement `registry.purgeExpired()` — delegates to TTL manager; emits `expired` for each.
+- [x] Write `registry.test.ts` (≤500 lines): register, lookup, health update, TTL expiry, subscription notification, capacity exceeded.
+- [x] Write `registry.md` (≥200 words).
+
+---
+
+## 6. Property-based tests (`tests/property.test.ts`)
+
+- [x] `lookup(q)` results are always a subset of `list()`.
+- [x] After `purgeExpired()`, no expired entries remain in `list()`.
+- [x] `capabilities` AND: result set is always subset of result with only one capability filter.
+
+---
+
+## 7. Docs and verify
+
+- [x] All per-file `.md` files per layout in `proposal.md`.
+- [x] `universal/network/network-registry/README.md`.
+- [x] `bunx turbo lint typecheck test test:coverage --filter=@suaveplan/network-registry` — all green, 100%.
+- [x] `bun scripts/publish.ts --package @suaveplan/network-registry`.
+- [x] Update `CLAUDE.md`. Archive change folder.