Unify supercomputer mesh into one virtual machine via cluster-fabric

Add hyper-p2p-cluster-fabric: aggregates every peer's CPU, RAM, GPU, disk, and bandwidth into a single logical supercomputer (clusterId, asOneMachine). - getVirtualMachine() — total vs available capacity across all nodes - publishNode() — join the giant computer; syncs attached pool modules - reserveCluster() — greedy multi-peer allocation for one workload - runClusterJob() — reserve + fan-out jobs across slices - Gossip cluster-node / cluster-reserve / cluster-run on Protomux Enhance hyper-p2p-capacity-registry with clusterTotals() for the same aggregate view at the registry layer. Update SUPERCOMPUTER_LAYERS, category README, demo (3 racks → 44 cores, 155 GB RAM, 5 GPUs as one machine). Registry now 165 modules. Co-authored-by: Cursor <[email protected]>
2026-05-21 00:41:57 -04:00
parent 693385bd7c
commit 03151a4cfc
17 changed files with 2442 additions and 22 deletions
@@ -0,0 +1,52 @@
+# API: hyper-p2p-cluster-fabric
+
+**Protocol:** `cluster-fabric/v1` · **Export:** `HyperP2PClusterFabric`
+
+## Overview
+
+Top-level **virtual supercomputer** facade. Every peer that `publishNode()` becomes part of one machine identified by `clusterId`. Workloads draw from **combined** CPU/RAM/GPU/disk across the mesh.
+
+## Constructor
+
+```js
+const fabric = new HyperP2PClusterFabric({
+  topic,
+  clusterId,       // optional; derived from topic hash
+  registry,        // optional HyperP2PCapacityRegistry
+  cpu, ram, gpu, jobs, thermal, affinity, bandwidth, disk  // optional attached modules
+})
+```
+
+## Methods
+
+### `publishNode(resources, peerId?) → nodeRecord`
+
+Registers a node on the fabric; forwards to attached modules (`advertise`, `donate`, `lend`, `offer`, etc.).
+
+### `getVirtualMachine() → { clusterId, name, nodes, total, available, asOneMachine }`
+
+Single view of the **entire** mesh as one computer.
+
+### `clusterTotals()` / `availableTotals()`
+
+Aggregated capacity and remaining free resources.
+
+### `reserveCluster({ cpuMs, ramMb, gpuSlots, diskGb }) → reservation`
+
+Greedy placement across peers; returns `{ reservationId, slices: [{ peerId, cpuMs, ramMb, ... }] }`.
+
+### `releaseReservation(reservationId) → boolean`
+
+### `runClusterJob(spec) → { reservationId, slices, jobIds }`
+
+Calls `reserveCluster` then `jobs.submitJob` per slice when `jobs` is attached.
+
+### `listNodes()` / `mergeCluster(remote)` / `getStats()` / `ready()` / `close()`
+
+## Events
+
+`node`, `reserve`, `release`, `run`, `merge`, `closed`
+
+## Composition
+
+Sits above all other `supercomputer/*` modules. See [`../../_shared/SUPERCOMPUTER_LAYERS.md`](../../_shared/SUPERCOMPUTER_LAYERS.md).
@@ -0,0 +1,29 @@
+# Architecture: hyper-p2p-cluster-fabric
+
+```text
+                    ┌─────────────────────────────┐
+                    │   HyperP2PClusterFabric     │
+                    │   (one virtual machine)     │
+                    └──────────────┬──────────────┘
+           ┌──────────┼──────────┬──────────┬──────────┐
+           ▼          ▼          ▼          ▼          ▼
+     capacity    cpu-share   ram-pool   gpu-slot   job-dispatcher
+     registry                                              ...
+           └──────────┴──────────┴──────────┴──────────┘
+                              Hyperswarm topic
+```
+
+## Wire messages
+
+| type | Purpose |
+|------|---------|
+| `cluster-node` | Gossip node capacity into fabric view |
+| `cluster-reserve` | Shared reservation across mesh |
+| `cluster-release` | Release reservation |
+| `cluster-run` | Announced cluster job fan-out |
+
+## State
+
+- `_nodes` — per-peer contributed capacity + usage
+- `_reservations` — active multi-peer allocations
+- `_used` — cluster-wide reserved totals