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

OpenSpec Change: network-plugin-registry

• Change ID: network-plugin-registry
• Package: @suaveplan/network-plugin-registry (new)
• Status: PROPOSED
• Type: new-package
• Date: 2026-04-29

Why

The tiered network requires a small, fixed-size registry of group peers. The genesis bitpacker package provides the binary serialization needed for compact messages (62 bytes vs ~200 bytes JSON). The genesis storage package provides the KV backing. This plugin provides the registry operations: add, remove, get, list, plus BinaryMessageEncoder for compact wire format. It is the authoritative replacement for the suaveplan network-registry package.

What changes

• ADDED: RegistryPlugin class implementing NetworkPlugin.
• ADDED: Registry — CRUD on a fixed-capacity in-memory registry.
• ADDED: BinaryMessageEncoder — packs DynamicData into bit-packed binary using @suaveplan/bitpacker.
• ADDED: RegistryMessage — union type for add, remove, get, list operations.
• ADDED: RegistrySyncManager — periodically syncs registry state to NetworkBus.
• ADDED: NETWORK_REG_CODES — frozen error registry.

Out of scope

• Distributed consensus for registry consistency → groups are small; eventual consistency via bus is sufficient.
• Persistent registry storage → future network-plugin-registry-persistence using @suaveplan/storage.
• Cross-group registry federation → future scope.

Source mapping

This change derives from ../suaveplan/enterprise/network-registry.md and ../suaveplan/packages/universal/network-registry/.

Requirement	Source lines	Notes
Fixed-capacity registry (32 peers)	network-registry/README.md §Registry	verbatim
add, remove, get, list	network-registry/README.md §Registry	verbatim
Binary message encoder (62 bytes)	network-registry/README.md §Binary Message Encoder	verbatim; uses @suaveplan/bitpacker
registry:update bus event	network-registry/README.md §Registry	reworded; emits on NetworkBus

Requirements with no source line

Requirement	Justification
RegistrySyncManager with periodic sync	Defensive — ensures registry converges after partition
NETWORK_REG_CODES	Required by spec-conformance for every enterprise package

Verification approach

• src/registry/registry.spec-conformance.test.ts — pins add/remove/get/list, capacity limit.
• src/encoder/encoder.spec-conformance.test.ts — pins binary format, roundtrip, size ≤ 62 bytes.
• src/sync/sync.spec-conformance.test.ts — pins periodic sync, deduplication.
• tests/dep-graph.test.ts — pins direct import of @suaveplan/bitpacker.

Migration impact

None — additive only.