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

Tasks — network-plugin-registry

Blocked on: network-core.

1. Scaffold

• 1.1 packages/network/network-plugin-registry/ with package.json (@suaveplan/network-plugin-registry@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/bitpacker, @suaveplan/storage, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/registry.types.ts — RegistryEntry, RegistryConfig, RegistryMessage.
• 2.2 src/types/encoder.types.ts — DynamicData, EncodedMessage.
• 2.3 src/error-codes.ts — defineCodes("NET_REG", [...]).

3. Registry

• 3.1 src/registry/registry.ts — Registry with fixed capacity (default 32).
• 3.2 add(entry), remove(peerId), get(peerId), list().
• 3.3 RegistryCapacityExceededError when capacity reached.
• 3.4 Emits registry:update on NetworkBus.

4. Binary message encoder

• 4.1 src/encoder/binary-message-encoder.ts — BinaryMessageEncoder.
• 4.2 Packs DynamicData into BitPacker format.
• 4.3 Target ≤ 62 bytes per message.
• 4.4 Roundtrip encoding/decoding with BinaryMessageDecoder.

5. Sync manager

• 5.1 src/sync/registry-sync-manager.ts — RegistrySyncManager.
• 5.2 Periodic full sync on NetworkBus.
• 5.3 Deduplication by hash.

6. Plugin wrapper

• 6.1 src/plugin/registry-plugin.ts — RegistryPlugin implements NetworkPlugin.
• 6.2 Installs registry, encoder, sync manager on install().

7. Spec

• 7.1 Update openspec/specs/network/spec.md with NET-12, NET-13.

8. Conformance tests

• 8.1 src/registry/registry.spec-conformance.test.ts — add/remove/get/list, capacity limit.
• 8.2 src/encoder/encoder.spec-conformance.test.ts — binary format, roundtrip, size ≤ 62 bytes.
• 8.3 src/sync/sync.spec-conformance.test.ts — periodic sync, deduplication.
• 8.4 src/error-codes.spec-conformance.test.ts — frozen registry.

9. Verify

• 9.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-registry green.
• 9.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-registry 100/100/100/100.
• 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.