# @suaveplan/network-plugin-server-bridge - Tier-0 host ↔ central-server bridge for the Suaveplan mesh: ServerGateway (transport-agnostic, 2× heartbeat disconnect detection), GracefulDegradationFsm (online → degrading → offline → recovering → online), OfflineModeCoordinator (autonomous mode + token-grace extension), LogBuffer (circular signed-log replay queue), ReconciliationProtocol (server-watermark-driven differential with LWW conflict resolution), CommandDispatcher (Ed25519 signature + nonce-replay protection), HeartbeatMultiplexer (Tier-0 batch forwarding), four hosting-model coordinators (PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP), and ServerBridgePlugin facade with tier gate.

## Summary

Tier-0 host ↔ central-server bridge for the Suaveplan mesh.

`ServerBridgePlugin` ties together every subsystem the bridge needs:

- **`ServerGateway`** — transport-agnostic byte channel with a heartbeat loop and 2× heartbeat disconnect detection.
- **`GracefulDegradationFsm`** — five-state FSM (`online → degrading → offline → recovering → online`) with strict transition validation.
- **`OfflineModeCoordinator`** — switches mesh to autonomous mode on disconnect, extends token grace, blocks new sessions, emits `server:offline` / `server:online`.
- **`LogBuffer`** — circular replay queue for signed activity logs with `entryHash` dedup, `seq`-ordered drain, partial-progress cursor.
- **`ReconciliationProtocol`** — server-watermark-driven differential with last-writer-wins conflict resolution (host wins ties).
- **`CommandDispatcher`** — Ed25519 signature validation (verifier injected), nonce + maxAge replay protection, dispatch to per-type handlers and `command:<type>` bus topics.
- **`HeartbeatMultiplexer`** — Tier-0 batches per-peer heartbeats and forwards aggregated batches upstream so peers don't each open a server WebSocket.
- **Hosting models** — four coordinators (`PureClientCoordinator`, `ServerBasedCoordinator`, `FailoverCoordinator`, `BackupCoordinator`) implementing `PURE_CLIENT`, `SERVER_BASED`, `SERVER_TO_CLIENT_FAILOVER`, `CLIENT_WITH_SERVER_BACKUP` per `NET-56`.

<!-- begin:auto-docs -->
## Documentation tree

- [buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [log-buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [command](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [command-dispatcher](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [error-codes](./src/error-codes/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…
  - [error-codes](./src/error-codes/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…
- [fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [server-gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…
- [failover-coordinator](./src/hosting/failover-coordinator.md) — `FailoverCoordinator` implements the `SERVER_TO_CLIENT_FAILOVER` model — the proposal's current default. The server is…
- [hosting-model-config](./src/hosting/hosting-model-config.md) — `hostingModelConfig(model)` is the single accessor for the four hosting-model presets the proposal documents (`PURE_CLI…
- [pure-client-coordinator](./src/hosting/pure-client-coordinator.md) — `PureClientCoordinator` implements the `PURE_CLIENT` hosting model: no central server is in the picture, and token issu…
- [server-based-coordinator](./src/hosting/server-based-coordinator.md) — `ServerBasedCoordinator` implements the `SERVER_BASED` hosting model: the server is always the top-tier host, clients n…
- [multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [heartbeat-multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [offline](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [offline-mode-coordinator](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [server-bridge-plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [reconciliation](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [reconciliation-protocol](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [log-buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_- [command](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [command-dispatcher](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…
- [failover-coordinator](./src/hosting/failover-coordinator.md) — `FailoverCoordinator` implements the `SERVER_TO_CLIENT_FAILOVER` model — the proposal's current default. The server is…
- [hosting-model-config](./src/hosting/hosting-model-config.md) — `hostingModelConfig(model)` is the single accessor for the four hosting-model presets the proposal documents (`PURE_CLI…
- [pure-client-coordinator](./src/hosting/pure-client-coordinator.md) — `PureClientCoordinator` implements the `PURE_CLIENT` hosting model: no central server is in the picture, and token issu…
- [server-based-coordinator](./src/hosting/server-based-coordinator.md) — `ServerBasedCoordinator` implements the `SERVER_BASED` hosting model: the server is always the top-tier host, clients n…
- [multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [heartbeat-multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline-mode-coordinator](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-bridge-plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation-protocol](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…
- [log-buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_- [command](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [command-dispatcher](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…
- [failover-coordinator](./src/hosting/failover-coordinator.md) — `FailoverCoordinator` implements the `SERVER_TO_CLIENT_FAILOVER` model — the proposal's current default. The server is…
- [hosting-model-config](./src/hosting/hosting-model-config.md) — `hostingModelConfig(model)` is the single accessor for the four hosting-model presets the proposal documents (`PURE_CLI…
- [pure-client-coordinator](./src/hosting/pure-client-coordinator.md) — `PureClientCoordinator` implements the `PURE_CLIENT` hosting model: no central server is in the picture, and token issu…
- [server-based-coordinator](./src/hosting/server-based-coordinator.md) — `ServerBasedCoordinator` implements the `SERVER_BASED` hosting model: the server is always the top-tier host, clients n…
- [multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [heartbeat-multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline-mode-coordinator](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-bridge-plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation-protocol](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…
- [log-buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_- [command](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [command-dispatcher](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…
- [failover-coordinator](./src/hosting/failover-coordinator.md) — `FailoverCoordinator` implements the `SERVER_TO_CLIENT_FAILOVER` model — the proposal's current default. The server is…
- [hosting-model-config](./src/hosting/hosting-model-config.md) — `hostingModelConfig(model)` is the single accessor for the four hosting-model presets the proposal documents (`PURE_CLI…
- [pure-client-coordinator](./src/hosting/pure-client-coordinator.md) — `PureClientCoordinator` implements the `PURE_CLIENT` hosting model: no central server is in the picture, and token issu…
- [server-based-coordinator](./src/hosting/server-based-coordinator.md) — `ServerBasedCoordinator` implements the `SERVER_BASED` hosting model: the server is always the top-tier host, clients n…
- [multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [heartbeat-multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline-mode-coordinator](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [server-bridge-plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation-protocol](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…
- [log-buffer](./src/buffer/log-buffer.md) — <!-- begin:auto-docs --> _(no submodules)_- [command](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_  - [command-dispatcher](./src/command/command-dispatcher.md) — <!-- begin:auto-docs --> _(no submodules)_- [fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_  - [graceful-degradation-fsm](./src/fsm/graceful-degradation-fsm.md) — <!-- begin:auto-docs --> _(no submodules)_- [gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_  - [server-gateway](./src/gateway/server-gateway.md) — <!-- begin:auto-docs --> _(no submodules)_- [backup-coordinator](./src/hosting/backup-coordinator.md) — `BackupCoordinator` implements the `CLIENT_WITH_SERVER_BACKUP` model: clients host normally and the server is a backup…
- [failover-coordinator](./src/hosting/failover-coordinator.md) — `FailoverCoordinator` implements the `SERVER_TO_CLIENT_FAILOVER` model — the proposal's current default. The server is…
- [hosting-model-config](./src/hosting/hosting-model-config.md) — `hostingModelConfig(model)` is the single accessor for the four hosting-model presets the proposal documents (`PURE_CLI…
- [pure-client-coordinator](./src/hosting/pure-client-coordinator.md) — `PureClientCoordinator` implements the `PURE_CLIENT` hosting model: no central server is in the picture, and token issu…
- [server-based-coordinator](./src/hosting/server-based-coordinator.md) — `ServerBasedCoordinator` implements the `SERVER_BASED` hosting model: the server is always the top-tier host, clients n…
- [multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_  - [heartbeat-multiplexer](./src/multiplexer/heartbeat-multiplexer.md) — <!-- begin:auto-docs --> _(no submodules)_- [offline](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_  - [offline-mode-coordinator](./src/offline/offline-mode-coordinator.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_  - [server-bridge-plugin](./src/plugin/server-bridge-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [reconciliation](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_  - [reconciliation-protocol](./src/reconciliation/reconciliation-protocol.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_SB` error registry for `@suaveplan/network-plugin-server-bridge`. Every failure path the server bridge can…

## Install

```bash
bun add @suaveplan/network-plugin-server-bridge
```

## Quick start

```ts
import { NetworkBus, NetworkNode } from "@suaveplan/network";
import {
    FailoverCoordinator,
    ServerBridgePlugin,
} from "@suaveplan/network-plugin-server-bridge";

const node = new NetworkNode({ id: "host-1", networkBus: new NetworkBus() });
const plugin = new ServerBridgePlugin({
    tierGate: () => topology.localTier() === 0,
    transportFactory: () => openWebSocket(serverUrl),
    heartbeatIntervalMs: 1_000,
    bufferCapacity: 10_000,
    tokenGraceMs: 30_000,
    extendedTokenGraceMs: 5 * 60_000,
    verifyCommand: (canon, sig) => ed25519Verify(sig, canon, serverPubKey),
    currentMeshEpoch: () => meshEpoch.current(),
    sessionAttributor: (entry) => extractSession(entry),
    hostingCoordinator: new FailoverCoordinator({
        serverAvailable: () => gateway.connectionState() === "open",
        mintToken: (req) => sign(req),
    }),
    heartbeatBatchWindowMs: 500,
    heartbeatSink: async (batch) => gateway.send(encode(batch)),
});

node.use(plugin);
await node.start();
```

## Modules

- [`error-codes`](./src/error-codes.md) — `NETWORK_SB_CODES` registry + `NetworkSbError`.
- [`fsm/graceful-degradation-fsm`](./src/fsm/graceful-degradation-fsm.md) — five-state bridge FSM.
- [`gateway/server-gateway`](./src/gateway/server-gateway.md) — heartbeat loop + 2× disconnect detection.
- [`gateway/server-gateway.types`](./src/gateway/server-gateway.types.md) — gateway shapes.
- [`offline/offline-mode-coordinator`](./src/offline/offline-mode-coordinator.md) — autonomous mode + grace extension.
- [`buffer/log-buffer`](./src/buffer/log-buffer.md) — circular replay queue.
- [`reconciliation/reconciliation-protocol`](./src/reconciliation/reconciliation-protocol.md) — diff + LWW conflict.
- [`reconciliation/reconciliation-protocol.types`](./src/reconciliation/reconciliation-protocol.types.md) — reconciliation shapes.
- [`command/command-dispatcher`](./src/command/command-dispatcher.md) — signed-command pipeline.
- [`command/command-dispatcher.types`](./src/command/command-dispatcher.types.md) — dispatcher shapes.
- [`multiplexer/heartbeat-multiplexer`](./src/multiplexer/heartbeat-multiplexer.md) — Tier-0 batch forwarding.
- [`hosting/hosting-model-config`](./src/hosting/hosting-model-config.md) — four-model preset accessor.
- [`hosting/pure-client-coordinator`](./src/hosting/pure-client-coordinator.md) — Byzantine quorum.
- [`hosting/server-based-coordinator`](./src/hosting/server-based-coordinator.md) — server-only authority.
- [`hosting/failover-coordinator`](./src/hosting/failover-coordinator.md) — current default.
- [`hosting/backup-coordinator`](./src/hosting/backup-coordinator.md) — client-primary, server-backup.
- [`plugin/server-bridge-plugin`](./src/plugin/server-bridge-plugin.md) — facade satisfying `NetworkPlugin`.