@rljson/network 0.0.1

package/dist/network.js

@@ -0,0 +1,1691 @@
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { homedir, hostname, networkInterfaces } from "node:os";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { createSocket } from "node:dgram";
+import { connect } from "node:net";
+// @license
+const exampleNodeInfo = {
+  nodeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  hostname: "WORKSTATION-7",
+  localIps: ["192.168.1.42"],
+  domain: "office-sync",
+  port: 3e3,
+  startedAt: 1741123456789
+};
+// @license
+const examplePeerProbe = {
+  fromNodeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  toNodeId: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+  reachable: true,
+  latencyMs: 0.3,
+  measuredAt: 1741123456800
+};
+// @license
+const nodeRoles = ["hub", "client", "unassigned"];
+const formedByValues = [
+  "broadcast",
+  "cloud",
+  "election",
+  "manual",
+  "static"
+];
+const exampleNetworkTopology = {
+  domain: "office-sync",
+  hubNodeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  hubAddress: "192.168.1.42:3000",
+  formedBy: "broadcast",
+  formedAt: 1741123456800,
+  nodes: {
+    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
+      nodeId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      hostname: "WORKSTATION-7",
+      localIps: ["192.168.1.42"],
+      domain: "office-sync",
+      port: 3e3,
+      startedAt: 1741123456789
+    }
+  },
+  probes: [],
+  myRole: "hub"
+};
+// @license
+function defaultNetworkConfig(domain, port) {
+  return {
+    domain,
+    port,
+    broadcast: { enabled: true, port: 41234 },
+    probing: { enabled: true }
+  };
+}
+// @license
+const networkEventNames = [
+  "topology-changed",
+  "role-changed",
+  "hub-changed",
+  "peer-joined",
+  "peer-left"
+];
+const exampleTopologyChangedEvent = {
+  topology: exampleNetworkTopology
+};
+const exampleRoleChangedEvent = {
+  previous: "unassigned",
+  current: "hub"
+};
+const exampleHubChangedEvent = {
+  previousHub: null,
+  currentHub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+};
+// @license
+function parseLocalIps(interfaces) {
+  const ips = [];
+  for (const infos of Object.values(interfaces)) {
+    /* v8 ignore if -- @preserve */
+    if (!infos) continue;
+    for (const info of infos) {
+      if (info.family === "IPv4" && !info.internal) {
+        ips.push(info.address);
+      }
+    }
+  }
+  return ips;
+}
+function defaultNodeIdentityDeps() {
+  return {
+    readNodeId: async (filePath) => {
+      try {
+        return (await readFile(filePath, "utf-8")).trim();
+      } catch {
+        return null;
+      }
+    },
+    writeNodeId: async (filePath, nodeId) => {
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, nodeId, "utf-8");
+    },
+    hostname: () => hostname(),
+    localIps: () => parseLocalIps(networkInterfaces()),
+    randomUUID: () => randomUUID(),
+    now: () => Date.now(),
+    homedir: () => homedir()
+  };
+}
+class NodeIdentity {
+  nodeId;
+  hostname;
+  localIps;
+  domain;
+  port;
+  startedAt;
+  constructor(info) {
+    this.nodeId = info.nodeId;
+    this.hostname = info.hostname;
+    this.localIps = [...info.localIps];
+    this.domain = info.domain;
+    this.port = info.port;
+    this.startedAt = info.startedAt;
+  }
+  /** Convert to a plain NodeInfo data object */
+  toNodeInfo() {
+    return {
+      nodeId: this.nodeId,
+      hostname: this.hostname,
+      localIps: [...this.localIps],
+      domain: this.domain,
+      port: this.port,
+      startedAt: this.startedAt
+    };
+  }
+  /**
+   * Create a NodeIdentity, loading or generating a persistent UUID.
+   * @param options - Configuration and optional dependency overrides
+   */
+  static async create(options) {
+    const deps = { ...defaultNodeIdentityDeps(), ...options.deps };
+    const identityDir = options.identityDir ?? join(deps.homedir(), ".rljson-network");
+    const nodeIdPath = join(identityDir, options.domain, "node-id");
+    let nodeId = await deps.readNodeId(nodeIdPath);
+    if (!nodeId) {
+      nodeId = deps.randomUUID();
+      await deps.writeNodeId(nodeIdPath, nodeId);
+    }
+    return new NodeIdentity({
+      nodeId,
+      hostname: deps.hostname(),
+      localIps: deps.localIps(),
+      domain: options.domain,
+      port: options.port,
+      startedAt: deps.now()
+    });
+  }
+}
+// @license
+function defaultCreateUdpSocket() {
+  const raw = createSocket({ type: "udp4", reuseAddr: true });
+  return {
+    bind(port) {
+      return new Promise((resolve, reject) => {
+        raw.once("error", reject);
+        raw.bind(port, () => {
+          raw.removeListener("error", reject);
+          resolve();
+        });
+      });
+    },
+    send(data, port, address) {
+      return new Promise((resolve, reject) => {
+        raw.send(data, 0, data.length, port, address, (err) => {
+          /* v8 ignore if -- @preserve */
+          if (err) {
+            reject(err);
+          } else {
+            resolve();
+          }
+        });
+      });
+    },
+    onMessage(handler) {
+      raw.on("message", handler);
+    },
+    setBroadcast(flag) {
+      raw.setBroadcast(flag);
+    },
+    close() {
+      return new Promise((resolve) => {
+        raw.close(resolve);
+      });
+    }
+  };
+}
+class BroadcastLayer {
+  /**
+   * Create a BroadcastLayer.
+   * @param _config - Broadcast configuration (port, interval, timeout)
+   * @param deps - Injectable dependencies for testing
+   */
+  constructor(_config, deps) {
+    this._config = _config;
+    this._createSocket = deps?.createSocket ?? defaultCreateUdpSocket;
+    this._selfTestTimeoutMs = deps?.selfTestTimeoutMs ?? 2e3;
+  }
+  name = "broadcast";
+  _active = false;
+  _socket = null;
+  _identity = null;
+  _broadcastTimer = null;
+  _timeoutTimer = null;
+  _selfTestCallback = null;
+  _peers = /* @__PURE__ */ new Map();
+  _listeners = /* @__PURE__ */ new Map();
+  _createSocket;
+  _selfTestTimeoutMs;
+  // .........................................................................
+  // Lifecycle
+  // .........................................................................
+  /**
+   * Start the broadcast layer.
+   *
+   * 1. Bind UDP socket to configured port
+   * 2. Set up message handler
+   * 3. Perform self-test (send broadcast, listen for loopback)
+   * 4. If self-test passes: start periodic broadcasting + timeout checker
+   * @param identity - This node's identity
+   * @returns true if broadcast is available, false otherwise
+   */
+  async start(identity) {
+    if (this._config?.enabled === false) {
+      return false;
+    }
+    this._identity = identity;
+    const port = this._config?.port ?? 41234;
+    this._socket = this._createSocket();
+    try {
+      await this._socket.bind(port);
+    } catch {
+      await this._socket.close();
+      this._socket = null;
+      return false;
+    }
+    this._socket.setBroadcast(true);
+    this._socket.onMessage((msg, rinfo) => {
+      this._handleMessage(msg, rinfo);
+    });
+    const selfTestPassed = await this._selfTest(port);
+    if (!selfTestPassed) {
+      await this._socket.close();
+      this._socket = null;
+      return false;
+    }
+    this._active = true;
+    const intervalMs = this._config?.intervalMs ?? 5e3;
+    this._broadcastTimer = setInterval(() => {
+      void this._sendBroadcast(port);
+    }, intervalMs);
+    const timeoutMs = this._config?.timeoutMs ?? 15e3;
+    this._timeoutTimer = setInterval(() => {
+      this._checkTimeouts(timeoutMs);
+    }, intervalMs);
+    return true;
+  }
+  /** Stop the layer and clean up resources */
+  async stop() {
+    if (this._broadcastTimer) {
+      clearInterval(this._broadcastTimer);
+      this._broadcastTimer = null;
+    }
+    if (this._timeoutTimer) {
+      clearInterval(this._timeoutTimer);
+      this._timeoutTimer = null;
+    }
+    if (this._active) {
+      for (const [nodeId] of this._peers) {
+        this._emit("peer-lost", nodeId);
+      }
+    }
+    if (this._socket) {
+      await this._socket.close();
+      this._socket = null;
+    }
+    this._peers.clear();
+    this._active = false;
+    this._identity = null;
+    this._selfTestCallback = null;
+    this._listeners.clear();
+  }
+  /** Whether this layer is currently active */
+  isActive() {
+    return this._active;
+  }
+  // .........................................................................
+  // Peer access
+  // .........................................................................
+  /** Get all currently known peers from broadcast discovery */
+  getPeers() {
+    return [...this._peers.values()].map((e) => e.info);
+  }
+  /**
+   * Broadcast does NOT assign a hub — hub is elected by NetworkManager.
+   * Always returns null.
+   */
+  getAssignedHub() {
+    return null;
+  }
+  // .........................................................................
+  // Events
+  // .........................................................................
+  /**
+   * Subscribe to layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // .........................................................................
+  // Internal
+  // .........................................................................
+  /**
+   * Self-test: send a broadcast and listen for loopback reception.
+   * @param port - The UDP port to broadcast on
+   * @returns true if own packet was received, false on timeout
+   */
+  _selfTest(port) {
+    return new Promise((resolve) => {
+      let resolved = false;
+      this._selfTestCallback = () => {
+        /* v8 ignore if -- @preserve */
+        if (!resolved) {
+          resolved = true;
+          resolve(true);
+        }
+      };
+      void this._sendBroadcast(port);
+      setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          this._selfTestCallback = null;
+          resolve(false);
+        }
+      }, this._selfTestTimeoutMs);
+    });
+  }
+  /**
+   * Send a broadcast packet containing this node's info.
+   * @param port - The UDP port to broadcast on
+   */
+  async _sendBroadcast(port) {
+    /* v8 ignore if -- @preserve */
+    if (!this._socket || !this._identity) return;
+    const info = this._identity.toNodeInfo();
+    const data = Buffer.from(JSON.stringify(info));
+    try {
+      await this._socket.send(data, port, "255.255.255.255");
+    } catch {
+    }
+  }
+  /**
+   * Handle an incoming broadcast message.
+   * @param msg - Raw UDP message
+   * @param _rinfo - Remote address info (unused — we use packet content)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _handleMessage(msg, _rinfo) {
+    let packet;
+    try {
+      packet = JSON.parse(msg.toString());
+    } catch {
+      return;
+    }
+    if (packet.domain !== this._identity?.domain) {
+      return;
+    }
+    if (packet.nodeId === this._identity?.nodeId) {
+      if (this._selfTestCallback) {
+        this._selfTestCallback();
+        this._selfTestCallback = null;
+      }
+      return;
+    }
+    const isNew = !this._peers.has(packet.nodeId);
+    this._peers.set(packet.nodeId, { info: packet, lastSeen: Date.now() });
+    if (isNew) {
+      this._emit("peer-discovered", packet);
+    }
+  }
+  /**
+   * Check for timed-out peers and remove them.
+   * @param timeoutMs - Maximum silence period before declaring peer lost
+   */
+  _checkTimeouts(timeoutMs) {
+    const now = Date.now();
+    for (const [nodeId, entry] of this._peers) {
+      if (now - entry.lastSeen > timeoutMs) {
+        this._peers.delete(nodeId);
+        this._emit("peer-lost", nodeId);
+      }
+    }
+  }
+  /**
+   * Emit a typed event to all registered listeners.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+function defaultCreateCloudHttpClient() {
+  return {
+    async register(endpoint, info, apiKey) {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const res = await fetch(`${endpoint}/register`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(info)
+      });
+      if (!res.ok) {
+        throw new Error(`Cloud register failed: ${res.status}`);
+      }
+      return await res.json();
+    },
+    async poll(endpoint, nodeId, domain, apiKey) {
+      const headers = {};
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const params = new URLSearchParams({ nodeId, domain });
+      const res = await fetch(`${endpoint}/peers?${params.toString()}`, {
+        method: "GET",
+        headers
+      });
+      if (!res.ok) {
+        throw new Error(`Cloud poll failed: ${res.status}`);
+      }
+      return await res.json();
+    },
+    async reportProbes(endpoint, nodeId, probes, apiKey) {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+      const res = await fetch(`${endpoint}/probes`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ nodeId, probes })
+      });
+      if (!res.ok) {
+        throw new Error(`Cloud reportProbes failed: ${res.status}`);
+      }
+    }
+  };
+}
+class CloudLayer {
+  /**
+   * Create a CloudLayer.
+   * @param _config - Cloud configuration (endpoint, apiKey, pollInterval)
+   * @param deps - Injectable dependencies for testing
+   */
+  constructor(_config, deps) {
+    this._config = _config;
+    this._httpClient = deps?.createHttpClient?.() ?? defaultCreateCloudHttpClient();
+  }
+  name = "cloud";
+  _active = false;
+  _identity = null;
+  _pollTimer = null;
+  _peers = /* @__PURE__ */ new Map();
+  _assignedHub = null;
+  _listeners = /* @__PURE__ */ new Map();
+  _httpClient;
+  // Backoff state
+  _consecutivePollFailures = 0;
+  _basePollIntervalMs = 3e4;
+  _currentPollIntervalMs = 3e4;
+  _maxBackoffMs = 3e5;
+  _reRegisterThreshold = 10;
+  // .........................................................................
+  // Lifecycle
+  // .........................................................................
+  /**
+   * Start the cloud layer.
+   *
+   * 1. Check if cloud is enabled and endpoint configured
+   * 2. Register this node with the cloud
+   * 3. Process initial peer list and hub assignment
+   * 4. Start periodic polling
+   * @param identity - This node's identity
+   * @returns true if cloud is available, false otherwise
+   */
+  async start(identity) {
+    if (this._active) return true;
+    if (this._config?.enabled !== true) {
+      return false;
+    }
+    if (!this._config.endpoint) {
+      return false;
+    }
+    this._identity = identity;
+    let response;
+    try {
+      response = await this._httpClient.register(
+        this._config.endpoint,
+        identity.toNodeInfo(),
+        this._config.apiKey
+      );
+    } catch {
+      return false;
+    }
+    this._active = true;
+    this._basePollIntervalMs = Math.max(
+      this._config.pollIntervalMs ?? 3e4,
+      100
+    );
+    this._currentPollIntervalMs = this._basePollIntervalMs;
+    this._maxBackoffMs = Math.max(this._config.maxBackoffMs ?? 3e5, 100);
+    this._reRegisterThreshold = Math.max(
+      this._config.reRegisterAfterFailures ?? 10,
+      1
+    );
+    this._consecutivePollFailures = 0;
+    this._processResponse(response);
+    this._schedulePoll();
+    return true;
+  }
+  /** Stop the layer and clean up resources */
+  async stop() {
+    if (this._pollTimer) {
+      clearTimeout(this._pollTimer);
+      this._pollTimer = null;
+    }
+    if (this._active) {
+      for (const [nodeId] of this._peers) {
+        this._emit("peer-lost", nodeId);
+      }
+    }
+    this._peers.clear();
+    this._assignedHub = null;
+    this._active = false;
+    this._identity = null;
+    this._listeners.clear();
+    this._consecutivePollFailures = 0;
+    this._currentPollIntervalMs = this._basePollIntervalMs;
+  }
+  /** Whether this layer is currently active */
+  isActive() {
+    return this._active;
+  }
+  // .........................................................................
+  // Peer access
+  // .........................................................................
+  /** Get all currently known peers from cloud discovery */
+  getPeers() {
+    return [...this._peers.values()];
+  }
+  /**
+   * Get the hub assigned by the cloud.
+   * The cloud **dictates** the hub — it has the full picture.
+   */
+  getAssignedHub() {
+    return this._assignedHub;
+  }
+  /** Get current consecutive poll failure count (for diagnostics/testing) */
+  getConsecutivePollFailures() {
+    return this._consecutivePollFailures;
+  }
+  /** Get current effective poll interval including backoff (for diagnostics/testing) */
+  getCurrentPollIntervalMs() {
+    return this._currentPollIntervalMs;
+  }
+  // .........................................................................
+  // Probe reporting
+  // .........................................................................
+  /**
+   * Report local probe results to the cloud.
+   * The cloud uses these to build a connectivity graph and assign hubs.
+   * @param probes - Probe results from the local ProbeScheduler
+   */
+  async reportProbes(probes) {
+    /* v8 ignore if -- @preserve */
+    if (!this._active || !this._identity || !this._config?.endpoint) return;
+    try {
+      await this._httpClient.reportProbes(
+        this._config.endpoint,
+        this._identity.nodeId,
+        probes,
+        this._config.apiKey
+      );
+    } catch {
+    }
+  }
+  // .........................................................................
+  // Events
+  // .........................................................................
+  /**
+   * Subscribe to layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // .........................................................................
+  // Internal
+  // .........................................................................
+  /**
+   * Schedule the next poll using setTimeout.
+   * Uses the current (possibly backed-off) interval.
+   */
+  _schedulePoll() {
+    this._pollTimer = setTimeout(() => {
+      void this._poll().catch(() => {
+      }).then(() => {
+        /* v8 ignore if -- @preserve */
+        if (this._active) this._schedulePoll();
+      });
+    }, this._currentPollIntervalMs);
+  }
+  /**
+   * Poll the cloud for latest peer list and hub assignment.
+   *
+   * After many consecutive failures, attempts re-registration instead
+   * of a regular poll (the cloud may have expired our registration).
+   *
+   * On success: resets failure counter and backoff interval.
+   * On failure: increments counter and doubles interval (capped at maxBackoffMs).
+   */
+  async _poll() {
+    /* v8 ignore if -- @preserve */
+    if (!this._identity || !this._config?.endpoint) return;
+    if (this._consecutivePollFailures >= this._reRegisterThreshold) {
+      let response2;
+      try {
+        response2 = await this._httpClient.register(
+          this._config.endpoint,
+          this._identity.toNodeInfo(),
+          this._config.apiKey
+        );
+      } catch {
+        this._consecutivePollFailures++;
+        this._currentPollIntervalMs = Math.min(
+          this._currentPollIntervalMs * 2,
+          this._maxBackoffMs
+        );
+        return;
+      }
+      this._consecutivePollFailures = 0;
+      this._currentPollIntervalMs = this._basePollIntervalMs;
+      this._processResponse(response2);
+      return;
+    }
+    let response;
+    try {
+      response = await this._httpClient.poll(
+        this._config.endpoint,
+        this._identity.nodeId,
+        this._identity.domain,
+        this._config.apiKey
+      );
+    } catch {
+      this._consecutivePollFailures++;
+      this._currentPollIntervalMs = Math.min(
+        this._currentPollIntervalMs * 2,
+        this._maxBackoffMs
+      );
+      return;
+    }
+    this._consecutivePollFailures = 0;
+    this._currentPollIntervalMs = this._basePollIntervalMs;
+    this._processResponse(response);
+  }
+  /**
+   * Process a cloud response: update peers and hub assignment.
+   * @param response - The cloud's peer list response
+   */
+  _processResponse(response) {
+    const currentPeerIds = new Set(this._peers.keys());
+    const newPeerIds = /* @__PURE__ */ new Set();
+    for (const peer of response.peers) {
+      if (peer.nodeId === this._identity?.nodeId) continue;
+      newPeerIds.add(peer.nodeId);
+      const isNew = !this._peers.has(peer.nodeId);
+      this._peers.set(peer.nodeId, peer);
+      if (isNew) {
+        this._emit("peer-discovered", peer);
+      }
+    }
+    for (const oldId of currentPeerIds) {
+      if (!newPeerIds.has(oldId)) {
+        this._peers.delete(oldId);
+        this._emit("peer-lost", oldId);
+      }
+    }
+    const previousHub = this._assignedHub;
+    this._assignedHub = response.assignedHub;
+    if (previousHub !== this._assignedHub) {
+      this._emit("hub-assigned", this._assignedHub);
+    }
+  }
+  /**
+   * Emit a typed event to all registered listeners.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+class ManualLayer {
+  name = "manual";
+  _active = false;
+  _assignedHub = null;
+  _listeners = /* @__PURE__ */ new Map();
+  /**
+   * Start always succeeds — manual layer cannot be disabled.
+   * @param _identity - Node identity (unused by manual layer)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async start(_identity) {
+    this._active = true;
+    return true;
+  }
+  /** Stop the layer */
+  async stop() {
+    this._active = false;
+    this._assignedHub = null;
+    this._listeners.clear();
+  }
+  /** Always active after start */
+  isActive() {
+    return this._active;
+  }
+  /** Manual layer does not discover peers */
+  getPeers() {
+    return [];
+  }
+  /** Get the manually assigned hub, or null if no override is set */
+  getAssignedHub() {
+    return this._assignedHub;
+  }
+  /**
+   * Force a specific node as the hub.
+   * @param nodeId - The nodeId to assign as hub
+   */
+  assignHub(nodeId) {
+    this._assignedHub = nodeId;
+    this._emit("hub-assigned", nodeId);
+  }
+  /** Clear the manual override — returns control to the automatic cascade */
+  clearOverride() {
+    this._assignedHub = null;
+    this._emit("hub-assigned", null);
+  }
+  /**
+   * Subscribe to layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // ...........................................................................
+  /**
+   * Emit a typed event to all registered listeners.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+class StaticLayer {
+  /**
+   * Create a StaticLayer.
+   * @param _config - Static config with optional hubAddress
+   */
+  constructor(_config) {
+    this._config = _config;
+  }
+  name = "static";
+  _active = false;
+  _hubAddress = null;
+  _hubNodeId = null;
+  _syntheticPeer = null;
+  _listeners = /* @__PURE__ */ new Map();
+  /**
+   * Start the layer. Returns false if no hubAddress is configured.
+   * @param identity - This node's identity (used for domain info on synthetic peer)
+   */
+  async start(identity) {
+    const hubAddress = this._config?.hubAddress;
+    if (!hubAddress) {
+      return false;
+    }
+    this._hubAddress = hubAddress;
+    this._hubNodeId = `static-hub-${hubAddress}`;
+    const colonIdx = hubAddress.lastIndexOf(":");
+    const host = colonIdx >= 0 ? hubAddress.substring(0, colonIdx) : hubAddress;
+    const port = colonIdx >= 0 ? parseInt(hubAddress.substring(colonIdx + 1), 10) : 3e3;
+    this._syntheticPeer = {
+      nodeId: this._hubNodeId,
+      hostname: `static-${host}`,
+      localIps: [host],
+      domain: identity.domain,
+      port,
+      startedAt: 0
+      // unknown
+    };
+    this._active = true;
+    this._emit("peer-discovered", this._syntheticPeer);
+    this._emit("hub-assigned", this._hubNodeId);
+    return true;
+  }
+  /** Stop the layer */
+  async stop() {
+    if (this._active && this._hubNodeId) {
+      this._emit("peer-lost", this._hubNodeId);
+    }
+    this._active = false;
+    this._hubAddress = null;
+    this._hubNodeId = null;
+    this._syntheticPeer = null;
+    this._listeners.clear();
+  }
+  /** Whether this layer is currently active */
+  isActive() {
+    return this._active;
+  }
+  /** Get the synthetic peer for the configured hub (or empty array) */
+  getPeers() {
+    if (!this._syntheticPeer) return [];
+    return [this._syntheticPeer];
+  }
+  /** Get the statically configured hub nodeId */
+  getAssignedHub() {
+    return this._hubNodeId;
+  }
+  /** Get the raw hub address string ("ip:port") */
+  getHubAddress() {
+    return this._hubAddress;
+  }
+  /**
+   * Subscribe to layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from layer events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // ...........................................................................
+  /**
+   * Emit a typed event to all registered listeners.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+class PeerTable {
+  /** All known peers, keyed by nodeId */
+  _peers = /* @__PURE__ */ new Map();
+  /** Per-layer peer sets, for deduplication tracking */
+  _layerPeers = /* @__PURE__ */ new Map();
+  /** Event listeners */
+  _listeners = /* @__PURE__ */ new Map();
+  /** Self nodeId — excluded from the peer table */
+  _selfId = null;
+  /**
+   * Set the self nodeId so it's excluded from the peer table.
+   * @param nodeId - This node's own ID
+   */
+  setSelfId(nodeId) {
+    this._selfId = nodeId;
+  }
+  /**
+   * Attach a discovery layer — subscribes to its peer events.
+   * Also imports any peers the layer already knows about.
+   * @param layer - The discovery layer to attach
+   */
+  attachLayer(layer) {
+    const layerName = layer.name;
+    if (!this._layerPeers.has(layerName)) {
+      this._layerPeers.set(layerName, /* @__PURE__ */ new Set());
+    }
+    for (const peer of layer.getPeers()) {
+      this._addPeerFromLayer(layerName, peer);
+    }
+    layer.on("peer-discovered", (peer) => {
+      this._addPeerFromLayer(layerName, peer);
+    });
+    layer.on("peer-lost", (nodeId) => {
+      this._removePeerFromLayer(layerName, nodeId);
+    });
+  }
+  /** Get all known peers as an array */
+  getPeers() {
+    return [...this._peers.values()];
+  }
+  /**
+   * Get a specific peer by nodeId.
+   * @param nodeId - The peer's nodeId
+   */
+  getPeer(nodeId) {
+    return this._peers.get(nodeId);
+  }
+  /** Get the number of known peers */
+  get size() {
+    return this._peers.size;
+  }
+  /** Clear all peers and layer tracking */
+  clear() {
+    this._peers.clear();
+    this._layerPeers.clear();
+    this._listeners.clear();
+  }
+  /**
+   * Subscribe to peer table events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from peer table events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // ...........................................................................
+  /**
+   * Add a peer from a specific layer.
+   * Only emits peer-joined if this is a genuinely new peer.
+   * @param layerName - Name of the source layer
+   * @param peer - The peer to add
+   */
+  _addPeerFromLayer(layerName, peer) {
+    if (this._selfId && peer.nodeId === this._selfId) return;
+    const layerSet = this._layerPeers.get(layerName);
+    layerSet.add(peer.nodeId);
+    const isNew = !this._peers.has(peer.nodeId);
+    this._peers.set(peer.nodeId, peer);
+    if (isNew) {
+      this._emit("peer-joined", peer);
+    }
+  }
+  /**
+   * Remove a peer from a specific layer.
+   * Only emits peer-left if no other layer still knows about this peer.
+   * @param layerName - Name of the source layer
+   * @param nodeId - The peer's nodeId
+   */
+  _removePeerFromLayer(layerName, nodeId) {
+    const layerSet = this._layerPeers.get(layerName);
+    /* v8 ignore else -- @preserve */
+    if (layerSet) {
+      layerSet.delete(nodeId);
+    }
+    for (const [name, set] of this._layerPeers) {
+      if (name !== layerName && set.has(nodeId)) {
+        return;
+      }
+    }
+    const peer = this._peers.get(nodeId);
+    if (peer) {
+      this._peers.delete(nodeId);
+      this._emit("peer-left", nodeId);
+    }
+  }
+  /**
+   * Emit a typed event.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+function electHub(candidates, probes, currentHubId, selfId) {
+  if (candidates.length === 0) {
+    return { hubId: null, reason: "no-candidates" };
+  }
+  const reachable = /* @__PURE__ */ new Set();
+  reachable.add(selfId);
+  for (const probe of probes) {
+    if (probe.reachable) {
+      reachable.add(probe.toNodeId);
+    }
+  }
+  const reachableCandidates = candidates.filter((c) => reachable.has(c.nodeId));
+  if (reachableCandidates.length === 0) {
+    return { hubId: null, reason: "no-candidates" };
+  }
+  if (currentHubId !== null) {
+    const incumbentStillReachable = reachableCandidates.some(
+      (c) => c.nodeId === currentHubId
+    );
+    if (incumbentStillReachable) {
+      return { hubId: currentHubId, reason: "incumbent" };
+    }
+  }
+  reachableCandidates.sort((a, b) => {
+    const timeDiff = a.startedAt - b.startedAt;
+    if (timeDiff !== 0) return timeDiff;
+    return a.nodeId.localeCompare(b.nodeId);
+  });
+  const winner = reachableCandidates[0];
+  const reason = reachableCandidates.length > 1 && reachableCandidates[1].startedAt === winner.startedAt ? "tiebreaker" : "earliest-start";
+  return { hubId: winner.nodeId, reason };
+}
+// @license
+async function probePeer(host, port, fromNodeId, toNodeId, options) {
+  const timeoutMs = options?.timeoutMs ?? 2e3;
+  const start = performance.now();
+  return new Promise((resolve) => {
+    const socket = connect({ host, port, timeout: timeoutMs });
+    const finish = (reachable) => {
+      const elapsed = performance.now() - start;
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve({
+        fromNodeId,
+        toNodeId,
+        reachable,
+        latencyMs: reachable ? Math.round(elapsed * 100) / 100 : -1,
+        measuredAt: Date.now()
+      });
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+// @license
+class ProbeScheduler {
+  _intervalMs;
+  _timeoutMs;
+  _failThreshold;
+  _selfId = "";
+  _running = false;
+  _timer = null;
+  /** Latest probe results, keyed by toNodeId */
+  _probes = /* @__PURE__ */ new Map();
+  /** Previous reachability state, for change detection */
+  _wasReachable = /* @__PURE__ */ new Map();
+  /** Consecutive failure count per peer, for flap dampening */
+  _failCount = /* @__PURE__ */ new Map();
+  /** Event listeners */
+  _listeners = /* @__PURE__ */ new Map();
+  /** The probe function — real TCP by default, injectable for tests */
+  _probeFn;
+  /** Peers to probe — updated externally via setPeers() */
+  _peers = [];
+  /**
+   * Create a ProbeScheduler.
+   * @param options - Configuration options
+   */
+  constructor(options) {
+    this._intervalMs = options?.intervalMs ?? 1e4;
+    this._timeoutMs = options?.timeoutMs ?? 2e3;
+    this._probeFn = options?.probeFn ?? probePeer;
+    this._failThreshold = options?.failThreshold ?? 3;
+  }
+  /**
+   * Start the scheduler.
+   * @param selfId - This node's ID (excluded from probing)
+   */
+  start(selfId) {
+    if (this._running) return;
+    this._selfId = selfId;
+    this._running = true;
+    void this._runCycle().then(() => {
+      if (this._running) this._scheduleNext();
+    });
+  }
+  /**
+   * Schedule the next probe cycle using setTimeout.
+   * Chaining (instead of setInterval) prevents overlapping cycles.
+   */
+  _scheduleNext() {
+    this._timer = setTimeout(() => {
+      void this._runCycle().then(() => {
+        /* v8 ignore else -- @preserve */
+        if (this._running) this._scheduleNext();
+      });
+    }, this._intervalMs);
+  }
+  /** Stop the scheduler and clear state */
+  stop() {
+    if (!this._running) return;
+    this._running = false;
+    /* v8 ignore if -- @preserve */
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    this._probes.clear();
+    this._wasReachable.clear();
+    this._failCount.clear();
+    this._peers = [];
+  }
+  /** Whether the scheduler is currently running */
+  isRunning() {
+    return this._running;
+  }
+  /**
+   * Update the list of peers to probe.
+   * Call this when the peer table changes.
+   * Self is automatically excluded at probe time.
+   * @param peers - The current peer list
+   */
+  setPeers(peers) {
+    this._peers = [...peers];
+    const currentPeerIds = new Set(peers.map((p) => p.nodeId));
+    for (const [nodeId] of this._probes) {
+      /* v8 ignore if -- @preserve */
+      if (!currentPeerIds.has(nodeId)) {
+        this._probes.delete(nodeId);
+        this._wasReachable.delete(nodeId);
+        this._failCount.delete(nodeId);
+      }
+    }
+  }
+  /** Get all latest probe results */
+  getProbes() {
+    return [...this._probes.values()];
+  }
+  /**
+   * Get the latest probe result for a specific peer.
+   * @param nodeId - The peer's nodeId
+   */
+  getProbe(nodeId) {
+    return this._probes.get(nodeId);
+  }
+  /**
+   * Run a single probe cycle manually.
+   * Useful for tests that need immediate results without waiting.
+   */
+  async runOnce() {
+    return this._runCycle();
+  }
+  // .........................................................................
+  // Events
+  // .........................................................................
+  /**
+   * Subscribe to scheduler events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from scheduler events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // .........................................................................
+  // Internal
+  // .........................................................................
+  /**
+   * Run one probe cycle: probe all peers in parallel.
+   */
+  async _runCycle() {
+    const peers = this._peers.filter((p) => p.nodeId !== this._selfId);
+    if (peers.length === 0) {
+      const empty = [];
+      this._emit("probes-updated", empty);
+      return empty;
+    }
+    const results = await Promise.all(
+      peers.map((peer) => {
+        const host = peer.localIps[0] ?? "127.0.0.1";
+        return this._probeFn(host, peer.port, this._selfId, peer.nodeId, {
+          timeoutMs: this._timeoutMs
+        });
+      })
+    );
+    for (const probe of results) {
+      const previous = this._wasReachable.get(probe.toNodeId);
+      this._probes.set(probe.toNodeId, probe);
+      if (probe.reachable) {
+        this._failCount.set(probe.toNodeId, 0);
+        this._wasReachable.set(probe.toNodeId, true);
+        if (previous !== void 0 && !previous) {
+          this._emit("peer-reachable", probe.toNodeId, probe);
+        }
+      } else {
+        const count = (this._failCount.get(probe.toNodeId) ?? 0) + 1;
+        this._failCount.set(probe.toNodeId, count);
+        if (count >= this._failThreshold) {
+          this._wasReachable.set(probe.toNodeId, false);
+          if (previous !== void 0 && previous) {
+            this._emit("peer-unreachable", probe.toNodeId, probe);
+          }
+          /* v8 ignore else -- @preserve */
+        } else if (previous === void 0) {
+          this._wasReachable.set(probe.toNodeId, false);
+        }
+      }
+    }
+    this._emit("probes-updated", results);
+    return results;
+  }
+  /**
+   * Emit a typed event.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+// @license
+class NetworkManager {
+  /**
+   * Create a NetworkManager.
+   * @param _config - Network configuration
+   * @param options - Optional overrides (e.g. custom probe function)
+   */
+  constructor(_config, options) {
+    this._config = _config;
+    this._broadcastLayer = new BroadcastLayer(
+      this._config.broadcast,
+      options?.broadcastDeps
+    );
+    this._cloudLayer = new CloudLayer(this._config.cloud, options?.cloudDeps);
+    this._staticLayer = new StaticLayer(this._config.static);
+    const probingConfig = this._config.probing;
+    this._probeScheduler = new ProbeScheduler({
+      intervalMs: probingConfig?.intervalMs ?? 1e4,
+      timeoutMs: probingConfig?.timeoutMs ?? 2e3,
+      probeFn: options?.probeFn,
+      failThreshold: options?.failThreshold
+    });
+  }
+  _identity = null;
+  _running = false;
+  /** Always-present manual override layer */
+  _manualLayer = new ManualLayer();
+  /** Try 1: UDP broadcast discovery */
+  _broadcastLayer;
+  /** Try 2: Cloud discovery fallback */
+  _cloudLayer;
+  /** Try 3: Static config fallback */
+  _staticLayer;
+  /** Merged peer table */
+  _peerTable = new PeerTable();
+  /** Probe scheduler for reachability checking */
+  _probeScheduler;
+  /** Event listeners */
+  _listeners = /* @__PURE__ */ new Map();
+  /** Current topology snapshot */
+  _currentHubId = null;
+  _currentRole = "unassigned";
+  _formedBy = "static";
+  // .........................................................................
+  // Lifecycle
+  // .........................................................................
+  /**
+   * Start the network manager.
+   *
+   * Creates node identity, starts all layers, attaches to peer table,
+   * and performs initial hub computation.
+   */
+  async start() {
+    if (this._running) return;
+    this._identity = await NodeIdentity.create({
+      domain: this._config.domain,
+      port: this._config.port,
+      identityDir: this._config.identityDir
+    });
+    this._peerTable.setSelfId(this._identity.nodeId);
+    this._peerTable.attachLayer(this._manualLayer);
+    this._peerTable.attachLayer(this._broadcastLayer);
+    this._peerTable.attachLayer(this._cloudLayer);
+    this._peerTable.attachLayer(this._staticLayer);
+    this._peerTable.on("peer-joined", (peer) => {
+      this._emit("peer-joined", peer);
+      this._probeScheduler.setPeers(this._peerTable.getPeers());
+      this._recomputeTopology();
+    });
+    this._peerTable.on("peer-left", (nodeId) => {
+      this._emit("peer-left", nodeId);
+      this._probeScheduler.setPeers(this._peerTable.getPeers());
+      this._recomputeTopology();
+    });
+    this._manualLayer.on("hub-assigned", () => {
+      this._recomputeTopology();
+    });
+    /* v8 ignore next -- @preserve */
+    this._broadcastLayer.on("hub-assigned", () => this._recomputeTopology());
+    this._cloudLayer.on("hub-assigned", () => {
+      this._recomputeTopology();
+    });
+    this._staticLayer.on("hub-assigned", () => {
+      this._recomputeTopology();
+    });
+    this._probeScheduler.on("probes-updated", () => {
+      this._recomputeTopology();
+    });
+    await this._manualLayer.start(this._identity);
+    await this._broadcastLayer.start(this._identity);
+    await this._cloudLayer.start(this._identity);
+    await this._staticLayer.start(this._identity);
+    const probingEnabled = this._config.probing?.enabled !== false;
+    if (probingEnabled) {
+      this._probeScheduler.setPeers(this._peerTable.getPeers());
+      this._probeScheduler.start(this._identity.nodeId);
+    }
+    this._running = true;
+    this._recomputeTopology();
+  }
+  /**
+   * Stop the network manager.
+   *
+   * Stops all layers and clears state.
+   */
+  async stop() {
+    if (!this._running) return;
+    this._probeScheduler.stop();
+    await this._manualLayer.stop();
+    await this._broadcastLayer.stop();
+    await this._cloudLayer.stop();
+    await this._staticLayer.stop();
+    this._peerTable.clear();
+    this._listeners.clear();
+    this._currentHubId = null;
+    this._currentRole = "unassigned";
+    this._running = false;
+  }
+  /** Whether the manager is currently running */
+  isRunning() {
+    return this._running;
+  }
+  // .........................................................................
+  // Topology access
+  // .........................................................................
+  /**
+   * Get the current topology snapshot.
+   * @returns The current network topology
+   */
+  getTopology() {
+    const nodes = /* @__PURE__ */ new Map();
+    for (const peer of this._peerTable.getPeers()) {
+      nodes.set(peer.nodeId, peer);
+    }
+    /* v8 ignore else -- @preserve */
+    if (this._identity) {
+      const selfInfo = this._identity.toNodeInfo();
+      nodes.set(selfInfo.nodeId, selfInfo);
+    }
+    return {
+      domain: this._config.domain,
+      hubNodeId: this._currentHubId,
+      hubAddress: this._resolveHubAddress(),
+      formedBy: this._formedBy,
+      formedAt: Date.now(),
+      nodes: Object.fromEntries(nodes),
+      probes: this._probeScheduler.getProbes(),
+      myRole: this._currentRole
+    };
+  }
+  /**
+   * Get the probe scheduler for direct access to probe results.
+   * @returns The ProbeScheduler instance
+   */
+  getProbeScheduler() {
+    return this._probeScheduler;
+  }
+  /**
+   * Get this node's identity.
+   * Throws if called before start().
+   */
+  getIdentity() {
+    /* v8 ignore if -- @preserve */
+    if (!this._identity) {
+      throw new Error("NetworkManager not started");
+    }
+    return this._identity;
+  }
+  // .........................................................................
+  // Manual override
+  // .........................................................................
+  /**
+   * Manually assign a hub node, overriding the cascade.
+   * @param nodeId - The node to designate as hub
+   */
+  assignHub(nodeId) {
+    this._manualLayer.assignHub(nodeId);
+  }
+  /**
+   * Clear the manual hub override, returning to cascade logic.
+   */
+  clearOverride() {
+    this._manualLayer.clearOverride();
+  }
+  // .........................................................................
+  // Events
+  // .........................................................................
+  /**
+   * Subscribe to network manager events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  on(event, cb) {
+    let set = this._listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._listeners.set(event, set);
+    }
+    set.add(cb);
+  }
+  /**
+   * Unsubscribe from network manager events.
+   * @param event - Event name
+   * @param cb - Callback
+   */
+  off(event, cb) {
+    const set = this._listeners.get(event);
+    /* v8 ignore if -- @preserve */
+    if (!set) return;
+    set.delete(cb);
+  }
+  // .........................................................................
+  // Internal
+  // .........................................................................
+  /**
+   * Compute the hub using the fallback cascade.
+   *
+   * Priority:
+   *   1. Manual override (human knows best)
+   *   2. Election among probed peers (most autonomous)
+   *      - formedBy 'broadcast' if broadcast layer provided peers
+   *      - formedBy 'election' otherwise
+   *   3. Cloud assignment (sees full picture, dictates hub)
+   *   4. Static config (last resort)
+   *   5. Nothing → unassigned
+   */
+  _computeHub() {
+    const manualHub = this._manualLayer.getAssignedHub();
+    if (manualHub) {
+      return { hubId: manualHub, formedBy: "manual" };
+    }
+    const probes = this._probeScheduler.getProbes();
+    if (probes.length > 0 && this._identity) {
+      const candidates = [
+        this._identity.toNodeInfo(),
+        ...this._peerTable.getPeers()
+      ];
+      const result = electHub(
+        candidates,
+        probes,
+        this._currentHubId,
+        this._identity.nodeId
+      );
+      /* v8 ignore else -- @preserve */
+      if (result.hubId) {
+        const formedBy = this._broadcastLayer.isActive() && this._broadcastLayer.getPeers().length > 0 ? "broadcast" : "election";
+        return { hubId: result.hubId, formedBy };
+      }
+    }
+    if (this._cloudLayer.isActive()) {
+      const cloudHub = this._cloudLayer.getAssignedHub();
+      if (cloudHub) {
+        return { hubId: cloudHub, formedBy: "cloud" };
+      }
+    }
+    if (this._staticLayer.isActive()) {
+      const staticHub = this._staticLayer.getAssignedHub();
+      /* v8 ignore else -- @preserve */
+      if (staticHub) {
+        return { hubId: staticHub, formedBy: "static" };
+      }
+    }
+    return { hubId: null, formedBy: "static" };
+  }
+  /**
+   * Recompute topology and emit events if anything changed.
+   */
+  _recomputeTopology() {
+    const { hubId, formedBy } = this._computeHub();
+    const previousHub = this._currentHubId;
+    const previousRole = this._currentRole;
+    this._currentHubId = hubId;
+    this._formedBy = formedBy;
+    if (!hubId) {
+      this._currentRole = "unassigned";
+    } else if (this._identity && hubId === this._identity.nodeId) {
+      this._currentRole = "hub";
+    } else {
+      this._currentRole = "client";
+    }
+    if (previousHub !== this._currentHubId) {
+      this._emit("hub-changed", {
+        previousHub,
+        currentHub: this._currentHubId
+      });
+    }
+    if (previousRole !== this._currentRole) {
+      this._emit("role-changed", {
+        previous: previousRole,
+        current: this._currentRole
+      });
+    }
+    this._emit("topology-changed", {
+      topology: this.getTopology()
+    });
+  }
+  /**
+   * Resolve the hub address ("ip:port") from the current hub.
+   * Uses static config's hubAddress if the hub is from static layer.
+   */
+  _resolveHubAddress() {
+    if (!this._currentHubId) return null;
+    if (this._formedBy === "static" && this._staticLayer.getHubAddress()) {
+      return this._staticLayer.getHubAddress();
+    }
+    const peer = this._peerTable.getPeer(this._currentHubId);
+    if (peer) {
+      /* v8 ignore next -- @preserve */
+      const ip = peer.localIps[0] ?? "unknown";
+      return `${ip}:${peer.port}`;
+    }
+    return null;
+  }
+  /**
+   * Emit a typed event.
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  _emit(event, ...args) {
+    const set = this._listeners.get(event);
+    if (!set) return;
+    for (const cb of set) {
+      cb(...args);
+    }
+  }
+}
+export {
+  BroadcastLayer,
+  CloudLayer,
+  ManualLayer,
+  NetworkManager,
+  NodeIdentity,
+  PeerTable,
+  ProbeScheduler,
+  StaticLayer,
+  defaultCreateCloudHttpClient,
+  defaultCreateUdpSocket,
+  defaultNetworkConfig,
+  defaultNodeIdentityDeps,
+  electHub,
+  exampleHubChangedEvent,
+  exampleNetworkTopology,
+  exampleNodeInfo,
+  examplePeerProbe,
+  exampleRoleChangedEvent,
+  exampleTopologyChangedEvent,
+  formedByValues,
+  networkEventNames,
+  nodeRoles,
+  parseLocalIps,
+  probePeer
+};