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

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.

5.5 KiB Raw Blame History