Massive Supercomputer pass: mesh factory, compute-shard, fabric depth

Turn the category into a production-ready unified virtual supercomputer.

New:
- _shared/supercomputer-mesh.js — createSupercomputerMesh() wires all 14 modules
- hyper-p2p-compute-shard — round-robin workload sharding across cluster peers

cluster-fabric:
- canFit, broadcastSnapshot, completeClusterRun
- cluster-snapshot gossip; fix RAM lend on publishNode

Pool modules — introspection helpers:
- capacity-registry: meetsRequirements, exportClusterView, listPeerIds
- cpu-share: totalPool, hasBalance
- ram-pool: lendMb, listLenders, availableBytes, listLeases
- disk-stripe: reassemble, clusterDiskBytes
- job-dispatcher: listJobs, runningCount, cancelJob
- gpu-slot: reserveCount, clusterGpuSlots
- bandwidth-share: clusterMbps
- net-gateway: bestGateway, totalCapacityBytes
- thermal-guard: throttledPeerIds, healthyPeerIds
- cluster-affinity: bestPeer
- work-stealer: totalPending, stealFromBusiest
- cache-farm: has, keys

Docs: SUPERCOMPUTER_LAYERS, category README, cluster-fabric api.md
Examples: demo-supercomputer-mesh uses createSupercomputerMesh

Registry: 166 modules (14 supercomputer)
Co-authored-by: Cursor <[email protected]>

supercomputer/hyper-p2p-cluster-fabric/docs/api.md

@@ -4,49 +4,60 @@
 
 ## 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.
+Unifies all peers into **one virtual supercomputer**. Sums CPU/RAM/GPU/disk/bandwidth, reserves across nodes, runs jobs, gossips cluster snapshots.
 
 ## 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
+  clusterId,
+  registry, cpu, ram, gpu, jobs, thermal, affinity, bandwidth, disk
 })
 ```
 
+Or use `createSupercomputerMesh()` from [`../../_shared/supercomputer-mesh.js`](../../_shared/supercomputer-mesh.js).
+
 ## Methods
 
 ### `publishNode(resources, peerId?) → nodeRecord`
 
-Registers a node on the fabric; forwards to attached modules (`advertise`, `donate`, `lend`, `offer`, etc.).
+Join the cluster; syncs attached pool modules.
 
 ### `getVirtualMachine() → { clusterId, name, nodes, total, available, asOneMachine }`
 
-Single view of the **entire** mesh as one computer.
-
 ### `clusterTotals()` / `availableTotals()`
 
-Aggregated capacity and remaining free resources.
+Aggregated capacity and free resources.
 
-### `reserveCluster({ cpuMs, ramMb, gpuSlots, diskGb }) → reservation`
+### `canFit({ cpuMs, ramMb, gpuSlots, diskGb }) → boolean`
 
-Greedy placement across peers; returns `{ reservationId, slices: [{ peerId, cpuMs, ramMb, ... }] }`.
+### `reserveCluster(spec) → { reservationId, slices, spec }`
+
+Greedy multi-peer allocation.
 
 ### `releaseReservation(reservationId) → boolean`
 
 ### `runClusterJob(spec) → { reservationId, slices, jobIds }`
 
-Calls `reserveCluster` then `jobs.submitJob` per slice when `jobs` is attached.
+Reserve + submit jobs per slice.
+
+### `completeClusterRun(run, results?) → boolean`
+
+Complete jobs and release reservation.
+
+### `broadcastSnapshot() → snapshot`
+
+Gossip full VM state to mesh.
 
 ### `listNodes()` / `mergeCluster(remote)` / `getStats()` / `ready()` / `close()`
 
 ## Events
 
-`node`, `reserve`, `release`, `run`, `merge`, `closed`
+`node`, `reserve`, `release`, `run`, `cluster-complete`, `snapshot`, `remote-snapshot`, `merge`, `closed`
 
-## Composition
+## Testing
 
-Sits above all other `supercomputer/*` modules. See [`../../_shared/SUPERCOMPUTER_LAYERS.md`](../../_shared/SUPERCOMPUTER_LAYERS.md).
+```bash
+npm install && npm test
+```