first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/networking/network/network-plugin-server-bridge/README.md
+++ b/docs/networking/network/network-plugin-server-bridge/README.md
@@ -0,0 +1,125 @@
+# @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`.