Initial Commit

openspec/archive/2026-05-10-network-plugin-server-bridge/tasks.md

@@ -0,0 +1,103 @@
+# Tasks — network-plugin-server-bridge
+
+> Blocked on: `network-core`, `network-plugin-audit-mesh`, `network-plugin-crypto-messages`.
+>
+> **Progress note (2026-05-10):** Scaffold + types + offline coordinator + degradation FSM are present. Core gateway, log buffer, reconciliation, command dispatcher, heartbeat multiplexer, and plugin wrapper are still missing. ~14/50 tasks complete.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-server-bridge/` with `package.json`, `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/retry`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/command.types.ts` — `ServerCommand`, `CommandType`.
+- [x] 2.2 `src/types/state.types.ts` — `BridgeState`, `OfflineMode`.
+- [x] 2.3 `src/types/buffer.types.ts` — `LogBufferConfig`, `BufferedEntry`.
+- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_SB", [...])`.
+
+## 3. Server gateway
+
+- [x] 3.1 `src/gateway/server-gateway.ts` — `ServerGateway`.
+- [x] 3.2 Persistent WebSocket to central server.
+- [x] 3.3 Heartbeat with configurable interval.
+- [x] 3.4 Detects disconnect within 2× heartbeat interval.
+
+## 4. Offline mode coordinator
+
+- [x] 4.1 `src/offline/offline-mode-coordinator.ts` — `OfflineModeCoordinator`.
+- [x] 4.2 Switches to autonomous mode on disconnect.
+- [x] 4.3 Extends token grace periods.
+- [x] 4.4 Broadcasts `server:offline` on bus.
+
+## 5. Log buffer
+
+- [x] 5.1 `src/buffer/log-buffer.ts` — `LogBuffer`.
+- [x] 5.2 Circular buffer of signed activity logs.
+- [x] 5.3 Replays to server on reconnection in sequence.
+
+## 6. Reconciliation protocol
+
+- [x] 6.1 `src/reconciliation/reconciliation-protocol.ts` — `ReconciliationProtocol`.
+- [x] 6.2 Server sends last known `meshEpoch` and sequences.
+- [x] 6.3 Host sends differential logs.
+- [x] 6.4 Conflict detection and resolution.
+
+## 7. Command dispatcher
+
+- [x] 7.1 `src/command/command-dispatcher.ts` — `CommandDispatcher`.
+- [x] 7.2 Validates server command signatures.
+- [x] 7.3 Dispatches to appropriate plugins via bus.
+
+## 8. Heartbeat multiplexer
+
+- [x] 8.1 `src/multiplexer/heartbeat-multiplexer.ts` — `HeartbeatMultiplexer`.
+- [x] 8.2 Aggregates peer heartbeats from Tier 0.
+- [x] 8.3 Forwards batched heartbeats to server.
+
+## 9. Graceful degradation FSM
+
+- [x] 9.1 `src/fsm/graceful-degradation-fsm.ts` — `online → degrading → offline → recovering → online`.
+- [x] 9.2 Uses `@suaveplan/fsm`.
+
+## 10. Plugin wrapper
+
+- [x] 10.1 `src/plugin/server-bridge-plugin.ts` — `ServerBridgePlugin` implements `NetworkPlugin`.
+- [x] 10.2 Only installs on Tier 0 hosts (no-op on lower tiers).
+
+## 11. Spec
+
+- [x] 11.1 Update `openspec/specs/network/spec.md` with `NET-SB` requirements.
+
+## 12. Conformance tests
+
+- [x] 12.1 `src/gateway/gateway.spec-conformance.test.ts` — connect, disconnect, heartbeat.
+- [x] 12.2 `src/offline/offline.spec-conformance.test.ts` — autonomous mode, grace extension.
+- [x] 12.3 `src/buffer/buffer.spec-conformance.test.ts` — buffering, replay, dedup.
+- [x] 12.4 `src/reconciliation/reconciliation.spec-conformance.test.ts` — epoch sync, conflict.
+- [x] 12.5 `src/command/command.spec-conformance.test.ts` — validation, dispatch, rejection.
+- [x] 12.6 `src/fsm/fsm.spec-conformance.test.ts` — state transitions.
+- [x] 12.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 14. Configurable hosting model
+
+- [x] 14.1 `src/hosting/hosting-model-config.ts` — `HostingModelConfig`, 4 models: PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP.
+- [x] 14.2 `src/hosting/pure-client-coordinator.ts` — `PureClientCoordinator`, Byzantine quorum for tokens.
+- [x] 14.3 `src/hosting/server-based-coordinator.ts` — `ServerBasedCoordinator`, server always hosts.
+- [x] 14.4 `src/hosting/failover-coordinator.ts` — `FailoverCoordinator`, current default (server → client).
+- [x] 14.5 `src/hosting/backup-coordinator.ts` — `BackupCoordinator`, client hosts, server overrides.
+
+## 15. Spec
+
+- [x] 15.1 Update `openspec/specs/network/spec.md` with `NET-56`.
+
+## 16. Conformance tests
+
+- [x] 16.1 `src/hosting/hosting.spec-conformance.test.ts` — 4 models, election behavior, token authority.
+
+## 17. Verify
+
+- [x] 17.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-server-bridge` green.
+- [x] 17.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-server-bridge` 100/100/100/100.
+- [x] 17.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-server-bridge` PASS.