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

Tasks — network-plugin-state

Blocked on: network-core, network-plugin-registry.

1. Scaffold

• 1.1 packages/network/network-plugin-state/ with package.json (@suaveplan/network-plugin-state@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/serialize, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/state.types.ts — StateValue, StatePath, StateSequence, StateSnapshot.
• 2.2 src/types/reconciliation.types.ts — ReconciliationStrategy, ConflictResolution, PathStrategy.
• 2.3 src/types/sync.types.ts — SyncMode, DeltaMessage, FullSyncMessage.
• 2.4 src/error-codes.ts — defineCodes("NET_STATE", [...]).

3. State manager

• 3.1 src/state/state-manager.ts — StateManager.
• 3.2 Path-based access: get(path), set(path, value), delete(path).
• 3.3 Versioned history with sequence numbers and timestamps.
• 3.4 Per-path subscriptions: subscribe(path, callback).

4. Delta compressor

• 4.1 src/delta/delta-compressor.ts — DeltaCompressor.
• 4.2 Computes deltas using @suaveplan/bitpacker.
• 4.3 Schema-aware compression for typed data.
• 4.4 Roundtrip encode/decode verification.

5. State reconciler

• 5.1 src/reconciler/state-reconciler.ts — StateReconciler.
• 5.2 Strategies: latest-wins, remote-wins, local-wins, deep-merge, custom.
• 5.3 Deterministic outcomes for same inputs.
• 5.4 Reports conflicts with path, local value, remote value.

6. Path strategy registry

• 6.1 src/strategy/path-strategy-registry.ts — PathStrategyRegistry.
• 6.2 Maps glob/regex patterns to reconciliation strategies.
• 6.3 Examples: game/positions/* → latest-wins, game/inventory/* → deep-merge.

7. Bloom filter comparator

• 7.1 src/bloom/bloom-filter-comparator.ts — BloomFilterComparator.
• 7.2 Generates compact Bloom filter from state paths.
• 7.3 Detects divergence with configurable false-positive rate (default 1%).

8. State sync engine

• 8.1 src/sync/state-sync-engine.ts — StateSyncEngine.
• 8.2 Full-state sync for new peers.
• 8.3 Delta sync for existing peers (Bloom filter divergence detection).
• 8.4 Conflict resolution via StateReconciler.
• 8.5 Notifies subscribers after sync.

9. Resource adapter

• 9.1 src/resource/resource-adapter.ts — ResourceAdapter.
• 9.2 Profiles: EDGE, MOBILE, DESKTOP, CLOUD.
• 9.3 Adjusts compression level, history retention, sync frequency per profile.

10. State history pruner

• 10.1 src/pruner/state-history-pruner.ts — StateHistoryPruner.
• 10.2 Configurable retention window (default: 5 minutes).
• 10.3 Memory-bound pruning: drops oldest when memory threshold exceeded.

11. Plugin wrapper

• 11.1 src/plugin/state-plugin.ts — StatePlugin implements NetworkPlugin.
• 11.2 Installs state manager, sync engine, pruner on install().
• 11.3 Subscribes to peer:joined for full-state sync, peer:left for cleanup.

12. Spec

• 12.1 Update openspec/specs/network/spec.md with NET-42.

13. Conformance tests

• 13.1 src/state/state.spec-conformance.test.ts — get/set, paths, history, subscriptions.
• 13.2 src/delta/delta.spec-conformance.test.ts — delta compute, roundtrip, schema.
• 13.3 src/reconciler/reconciler.spec-conformance.test.ts — 5 strategies, path-specific.
• 13.4 src/sync/sync.spec-conformance.test.ts — divergence, delta request, full sync.
• 13.5 src/bloom/bloom.spec-conformance.test.ts — filter comparison, false-positive tolerance.
• 13.6 src/resource/resource.spec-conformance.test.ts — profile adaptation.
• 13.7 src/pruner/pruner.spec-conformance.test.ts — retention, memory bounds.
• 13.8 src/error-codes.spec-conformance.test.ts — frozen registry.

14. Verify

• 14.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-state green.
• 14.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-state 100/100/100/100.
• 14.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-state PASS.