Initial Commit

openspec/changes/archive/2026-05-04-network-plugin-registry/tasks.md

@@ -0,0 +1,77 @@
+# Tasks — network-plugin-registry
+
+> Blocked on: `network-core`.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-registry/` with `package.json` (`@suaveplan/network-plugin-registry@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/bitpacker`, `@suaveplan/storage`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/registry.types.ts` — `RegistryEntry`, `RegistryConfig`, `RegistryMessage`.
+- [x] 2.2 `src/types/encoder.types.ts` — `DynamicData`, `EncodedMessage`.
+- [x] 2.3 `src/error-codes.ts` — `defineCodes("NET_REG", [...])`.
+
+## 3. Registry
+
+- [x] 3.1 `src/registry/registry.ts` — `Registry` with fixed capacity (default 32).
+- [x] 3.2 `add(entry)`, `remove(peerId)`, `get(peerId)`, `list()`.
+- [x] 3.3 `RegistryCapacityExceededError` when capacity reached.
+- [x] 3.4 Emits `registry:update` on `NetworkBus`.
+
+## 4. Binary message encoder
+
+- [x] 4.1 `src/encoder/binary-message-encoder.ts` — `BinaryMessageEncoder`.
+- [x] 4.2 Packs `DynamicData` into `BitPacker` format.
+- [x] 4.3 Target ≤ 62 bytes per message.
+- [x] 4.4 Roundtrip encoding/decoding with `BinaryMessageDecoder`.
+
+## 5. Sync manager
+
+- [x] 5.1 `src/sync/registry-sync-manager.ts` — `RegistrySyncManager`.
+- [x] 5.2 Periodic full sync on `NetworkBus`.
+- [x] 5.3 Deduplication by hash.
+
+## 6. Plugin wrapper
+
+- [x] 6.1 `src/plugin/registry-plugin.ts` — `RegistryPlugin` implements `NetworkPlugin`.
+- [x] 6.2 Installs registry, encoder, sync manager on `install()`.
+
+## 7. Spec
+
+- [x] 7.1 Update `openspec/specs/network/spec.md` with `NET-12`, `NET-13`.
+
+## 8. Conformance tests
+
+- [x] 8.1 `src/registry/registry.spec-conformance.test.ts` — add/remove/get/list, capacity limit.
+- [x] 8.2 `src/encoder/encoder.spec-conformance.test.ts` — binary format, roundtrip, size ≤ 62 bytes.
+- [x] 8.3 `src/sync/sync.spec-conformance.test.ts` — periodic sync, deduplication.
+- [x] 8.4 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 9. Verify
+
+- [x] 9.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-registry` green.
+- [x] 9.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-registry` 100/100/100/100.
+- [x] 9.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-registry` PASS.
+
+---
+
+## Audit Note (2026-05-02)
+
+**Status**: DEFERRED.
+
+State at audit:
+
+- Package scaffold is in place at `packages/network/network-plugin-registry/` with `src/registry/`, `src/encoder/`, `src/sync/`, plus `error-codes.ts`, `registry-plugin.ts`, and barrel `index.ts`. README, vite + vitest configs, tsconfig all exist.
+- `bunx turbo test --filter=@suaveplan/network-plugin-registry` is green (9 tests across `registry.spec-conformance.test.ts`, `encoder.spec-conformance.test.ts`, `dep-graph.test.ts`).
+- `bunx turbo test:coverage` **fails the 100/100/100/100 gate**: stmts 67.92 / branch 61.53 / funcs 52.38 / lines 67.92. `src/sync/sync.ts` is 0% covered (lines 11–30); `src/registry-plugin.ts` is 0% (lines 7–33); `src/registry/registry.ts` has one uncovered branch on line 14.
+
+Outstanding to ship:
+
+1. **Task 8.3** — author `src/sync/sync.spec-conformance.test.ts` covering periodic full-sync + dedup-by-hash; takes `RegistrySyncManager` to 100%.
+2. **Task 8.4** — author `src/error-codes.spec-conformance.test.ts` proving the `defineCodes("NET_REG", [...])` registry is frozen.
+3. **Tasks 6.1 / 6.2** — exercise `RegistryPlugin.install()` from a test (`src/registry-plugin.ts` is currently uncovered).
+4. **Task 3.3** — verify the `RegistryCapacityExceededError` branch (line 14 of `registry.ts`).
+5. Re-run `bunx turbo test:coverage --filter=@suaveplan/network-plugin-registry` and confirm 100/100/100/100, then archive.