56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# 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.
|