97 lines
5.5 KiB
Markdown
97 lines
5.5 KiB
Markdown
# OpenSpec Change: network-plugin-state
|
|
|
|
- **Change ID**: network-plugin-state
|
|
- **Package**: `@suaveplan/network-plugin-state` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
Multiplayer games and collaborative applications require synchronized state across all peers in a mesh. Without a dedicated state synchronization layer, each application must implement its own conflict resolution, delta compression, and reconnection handling. This leads to inconsistent state, bandwidth waste, and race conditions. The genesis `bitpacker` package provides efficient binary delta compression, and `serialize` provides schemas. This plugin implements a mesh-wide state store with automatic conflict resolution.
|
|
|
|
This plugin implements **synchronized state with delta compression, path-specific conflict resolution, and Bloom filter comparison** for efficient sync.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `StatePlugin` class implementing `NetworkPlugin`.
|
|
- **ADDED**: `StateManager` — maintains a versioned local state store with path-based access (`get(path)`, `set(path, value)`). Tracks state history with sequence numbers. Supports subscriptions per path.
|
|
- **ADDED**: `DeltaCompressor` — computes deltas between state versions using `@suaveplan/bitpacker`. Only changed properties are transmitted. Supports schema-aware compression for typed data.
|
|
- **ADDED**: `StateReconciler` — resolves conflicts between concurrent state updates with 5 strategies:
|
|
- `latest-wins` — highest timestamp wins
|
|
- `remote-wins` — always accept remote state
|
|
- `local-wins` — always keep local state
|
|
- `deep-merge` — combine non-conflicting properties recursively
|
|
- `custom` — application-provided merge function
|
|
- **ADDED**: `PathStrategyRegistry` — applies different reconciliation strategies per state path. Example: `game/positions` uses `latest-wins`, `game/inventory` uses `deep-merge`, `game/achievements` uses `remote-wins`.
|
|
- **ADDED**: `BloomFilterComparator` — uses Bloom filters for efficient state comparison. Peers exchange compact Bloom filter summaries to detect divergence without transmitting full state.
|
|
- **ADDED**: `StateSyncEngine` — orchestrates sync: detect divergence (Bloom filter), request delta, apply delta, resolve conflicts, notify subscribers. Supports full-state sync for new peers and delta sync for existing peers.
|
|
- **ADDED**: `ResourceAdapter` — adapts sync behavior based on device profile:
|
|
- `EDGE` — minimal history, aggressive compression, low sync frequency
|
|
- `MOBILE` — balanced compression, medium sync frequency, battery-aware
|
|
- `DESKTOP` — full history, fast sync, high responsiveness
|
|
- `CLOUD` — maximum throughput, aggressive batching
|
|
- **ADDED**: `StateHistoryPruner` — prunes old history based on memory constraints and policy. Configurable retention window.
|
|
- **ADDED**: `NETWORK_STATE_CODES` — frozen error registry.
|
|
|
|
## State sync flow
|
|
|
|
```text
|
|
Peer A changes state at path "game/positions/player1"
|
|
↓
|
|
StateManager records change with sequence + timestamp
|
|
↓
|
|
DeltaCompressor computes delta from previous version
|
|
↓
|
|
StateSyncEngine broadcasts delta to mesh peers
|
|
↓
|
|
Peer B receives delta
|
|
↓
|
|
StateReconciler applies strategy for "game/positions/*" (latest-wins)
|
|
↓
|
|
StateManager updates local state, notifies subscribers
|
|
```
|
|
|
|
## Out of scope
|
|
|
|
- Game-specific entity replication (ECS) → `gaming-ecs`, `gaming-r3f-networking`.
|
|
- Persistent state storage → future `network-plugin-state-persistence`.
|
|
- CRDT implementations → future `network-plugin-state-crdt`.
|
|
|
|
## Source mapping
|
|
|
|
This derives from `docs/old-network-planning/PHASE_7.md` §State Management and `PLAN_ENHANCED_PHASE_7.md`.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| State history tracking | `PHASE_7.md` §StateManager | reworded; path-based instead of object-based |
|
|
| Delta compression | `PHASE_7.md` §BitPackerCompressor | reworded; uses `@suaveplan/bitpacker` |
|
|
| Reconciliation strategies | `PHASE_7.md` §StateReconciler | verbatim: 5 strategies |
|
|
| Path-specific resolution | `PHASE_7.md` §Path-specific Resolution | verbatim |
|
|
| Bloom filter comparison | `ADAPT_3.md` §Performance Optimizations | reworded; for state divergence detection |
|
|
| Resource profiles | `PLAN_ENHANCED_PHASE_7.md` §Resource Profiles | reworded; 4 profiles |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| `StateSyncEngine` orchestration | Required to automate the full sync pipeline |
|
|
| `StateHistoryPruner` | Required to prevent unbounded memory growth |
|
|
| Subscriptions per path | Required for reactive UI updates |
|
|
|
|
## Verification approach
|
|
|
|
- `src/state/state.spec-conformance.test.ts` — pins get/set, path access, history, subscriptions.
|
|
- `src/delta/delta.spec-conformance.test.ts` — pins delta computation, roundtrip, schema encoding.
|
|
- `src/reconciler/reconciler.spec-conformance.test.ts` — pins all 5 strategies, path-specific application.
|
|
- `src/sync/sync.spec-conformance.test.ts` — pins divergence detection, delta request, full-state sync.
|
|
- `src/bloom/bloom.spec-conformance.test.ts` — pins filter comparison, false-positive tolerance.
|
|
- `src/resource/resource.spec-conformance.test.ts` — pins profile adaptation, compression level, sync frequency.
|
|
- `src/pruner/pruner.spec-conformance.test.ts` — pins retention window, memory bounds.
|
|
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
|
- `tests/dep-graph.test.ts` — pins direct import of `@suaveplan/bitpacker`.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|