Initial Commit

packages/networking/drive/drive-webrtc/src/peer-manager/topology/full-mesh.md

@@ -0,0 +1,79 @@
+# FullMeshStrategy
+
+## Purpose
+
+Every peer connects to every other peer up to a configurable cap.
+This is the default topology and matches the assumption baked into
+the drive-webrtc plugin: small (< 32) groups that benefit from
+direct peer-to-peer chunk transfers without a central relay. When
+capacity is reached, the strategy evicts the lowest-scoring existing
+peer if and only if the newcomer's score is strictly higher,
+preventing oscillation.
+
+## Features
+
+- Symmetric connect: `selectConnections` returns `[newPeer]` for
+  every new peer below `maxPeers`.
+- Score-gated eviction: never evicts unless a strictly better peer
+  arrives.
+- Self-peer never gets admitted to its own peer set.
+
+## Usage: Basic Example
+
+```ts
+import { FullMeshStrategy } from "@suaveplan/drive-webrtc";
+
+const strategy = new FullMeshStrategy();
+const decision = strategy.admitOrEvict([], newPeer, {
+    maxPeers: 10,
+    selfPeerId: "alice",
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    FullMeshStrategy,
+    PeerBandwidthTracker,
+} from "@suaveplan/drive-webrtc";
+
+const tracker = new PeerBandwidthTracker();
+const strategy = new FullMeshStrategy();
+const decision = strategy.admitOrEvict(currentPeers, newPeer, {
+    maxPeers: 4,
+    selfPeerId: "alice",
+    metricsFor: (id) => tracker.get(id),
+});
+if (decision.admit && decision.evict !== undefined) {
+    // PeerManager will evict `decision.evict` then admit `newPeer`.
+}
+```
+
+## API Reference
+
+### `new FullMeshStrategy()`
+
+No constructor parameters.
+
+### `selectConnections(current, newPeer, options)`
+
+Returns `[newPeer]` while `current.length < options.maxPeers` and
+`newPeer.id !== options.selfPeerId`. Empty otherwise.
+
+### `admitOrEvict(current, newPeer, options)`
+
+- Refuses duplicates (peer already in `current`).
+- Below capacity → admit with no eviction.
+- At capacity → find lowest-score existing peer; admit only if the
+  newcomer's score is strictly higher.
+
+## Implementation Notes
+
+- New peers default to score `1` (treated as healthy until a sample
+  exists), and existing peers without metrics default to `0.5`. This
+  biases admission toward fresh peers — desirable when scoring data
+  is sparse.
+- The strategy never returns `evict` unless `admit === true`. The
+  `PeerManager` does not need to handle a "kick this peer out
+  anyway" decision.