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

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

• 1.1 packages/network/network-plugin-server-bridge/ with package.json, tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/fsm, @suaveplan/retry, @suaveplan/timing, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/command.types.ts — ServerCommand, CommandType.
• 2.2 src/types/state.types.ts — BridgeState, OfflineMode.
• 2.3 src/types/buffer.types.ts — LogBufferConfig, BufferedEntry.
• 2.4 src/error-codes.ts — defineCodes("NET_SB", [...]).

3. Server gateway

• 3.1 src/gateway/server-gateway.ts — ServerGateway.
• 3.2 Persistent WebSocket to central server.
• 3.3 Heartbeat with configurable interval.
• 3.4 Detects disconnect within 2× heartbeat interval.

4. Offline mode coordinator

• 4.1 src/offline/offline-mode-coordinator.ts — OfflineModeCoordinator.
• 4.2 Switches to autonomous mode on disconnect.
• 4.3 Extends token grace periods.
• 4.4 Broadcasts server:offline on bus.

5. Log buffer

• 5.1 src/buffer/log-buffer.ts — LogBuffer.
• 5.2 Circular buffer of signed activity logs.
• 5.3 Replays to server on reconnection in sequence.

6. Reconciliation protocol

• 6.1 src/reconciliation/reconciliation-protocol.ts — ReconciliationProtocol.
• 6.2 Server sends last known meshEpoch and sequences.
• 6.3 Host sends differential logs.
• 6.4 Conflict detection and resolution.

7. Command dispatcher

• 7.1 src/command/command-dispatcher.ts — CommandDispatcher.
• 7.2 Validates server command signatures.
• 7.3 Dispatches to appropriate plugins via bus.

8. Heartbeat multiplexer

• 8.1 src/multiplexer/heartbeat-multiplexer.ts — HeartbeatMultiplexer.
• 8.2 Aggregates peer heartbeats from Tier 0.
• 8.3 Forwards batched heartbeats to server.

9. Graceful degradation FSM

• 9.1 src/fsm/graceful-degradation-fsm.ts — online → degrading → offline → recovering → online.
• 9.2 Uses @suaveplan/fsm.

10. Plugin wrapper

• 10.1 src/plugin/server-bridge-plugin.ts — ServerBridgePlugin implements NetworkPlugin.
• 10.2 Only installs on Tier 0 hosts (no-op on lower tiers).

11. Spec

• 11.1 Update openspec/specs/network/spec.md with NET-SB requirements.

12. Conformance tests

• 12.1 src/gateway/gateway.spec-conformance.test.ts — connect, disconnect, heartbeat.
• 12.2 src/offline/offline.spec-conformance.test.ts — autonomous mode, grace extension.
• 12.3 src/buffer/buffer.spec-conformance.test.ts — buffering, replay, dedup.
• 12.4 src/reconciliation/reconciliation.spec-conformance.test.ts — epoch sync, conflict.
• 12.5 src/command/command.spec-conformance.test.ts — validation, dispatch, rejection.
• 12.6 src/fsm/fsm.spec-conformance.test.ts — state transitions.
• 12.7 src/error-codes.spec-conformance.test.ts — frozen registry.

14. Configurable hosting model

• 14.1 src/hosting/hosting-model-config.ts — HostingModelConfig, 4 models: PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP.
• 14.2 src/hosting/pure-client-coordinator.ts — PureClientCoordinator, Byzantine quorum for tokens.
• 14.3 src/hosting/server-based-coordinator.ts — ServerBasedCoordinator, server always hosts.
• 14.4 src/hosting/failover-coordinator.ts — FailoverCoordinator, current default (server → client).
• 14.5 src/hosting/backup-coordinator.ts — BackupCoordinator, client hosts, server overrides.

15. Spec

• 15.1 Update openspec/specs/network/spec.md with NET-56.

16. Conformance tests

• 16.1 src/hosting/hosting.spec-conformance.test.ts — 4 models, election behavior, token authority.

17. Verify

• 17.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-server-bridge green.
• 17.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-server-bridge 100/100/100/100.
• 17.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-server-bridge PASS.