@rljson/network 0.0.1

package/dist/README.public.md

@@ -0,0 +1,426 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# @rljson/network
+
+Self-organizing network topology for the RLJSON ecosystem. Handles peer
+discovery, hub election, and topology formation — enabling nodes to
+automatically form star-topology networks without pre-assigned roles or
+hardcoded IPs.
+
+## Install
+
+```bash
+pnpm add @rljson/network
+```
+
+## Key Concepts
+
+| Concept          | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| **Domain**       | Groups nodes that should discover each other (not a DNS domain) |
+| **Hub**          | Central node elected automatically — all others are clients     |
+| **Discovery**    | Fallback cascade: Broadcast → Cloud → Static + Manual override  |
+| **Hub Election** | Incumbent advantage + earliest `startedAt` timestamp wins       |
+
+## Types
+
+### NodeInfo
+
+Describes a node in the network:
+
+```typescript
+import type { NodeInfo } from '@rljson/network';
+
+const node: NodeInfo = {
+  nodeId: 'a1b2c3d4-...',      // Persistent UUID
+  hostname: 'WORKSTATION-7',    // os.hostname()
+  localIps: ['192.168.1.42'],   // Non-internal IPv4 addresses
+  domain: 'office-sync',        // Network group
+  port: 3000,                   // Listen port when hub
+  startedAt: 1741123456789,     // Startup timestamp
+};
+```
+
+### PeerProbe
+
+Result of probing a peer's reachability:
+
+```typescript
+import type { PeerProbe } from '@rljson/network';
+
+const probe: PeerProbe = {
+  fromNodeId: 'node-a',
+  toNodeId: 'node-b',
+  reachable: true,
+  latencyMs: 12,
+  measuredAt: 1741123456800,
+};
+```
+
+### NetworkTopology
+
+Snapshot of the current network layout:
+
+```typescript
+import type { NetworkTopology } from '@rljson/network';
+
+const topo: NetworkTopology = {
+  domain: 'office-sync',
+  hubNodeId: 'a1b2c3d4-...',
+  hubAddress: '192.168.1.42:3000',
+  formedBy: 'broadcast',         // 'broadcast' | 'cloud' | 'election' | 'static' | 'manual'
+  formedAt: 1741123456800,
+  nodes: { /* NodeInfo by nodeId */ },
+  probes: [ /* PeerProbe[] */ ],
+  myRole: 'hub',                 // 'hub' | 'client' | 'unassigned'
+};
+```
+
+### NetworkConfig
+
+Configuration for the discovery layers:
+
+```typescript
+import { defaultNetworkConfig } from '@rljson/network';
+
+// Quick start — broadcast enabled, cloud/static off
+const config = defaultNetworkConfig('office-sync', 3000);
+
+// Full configuration
+import type { NetworkConfig } from '@rljson/network';
+
+const fullConfig: NetworkConfig = {
+  domain: 'office-sync',
+  port: 3000,
+  identityDir: '/opt/myapp/identity',  // Default: ~/.rljson-network/
+  broadcast: { enabled: true, port: 41234, intervalMs: 5000 },
+  cloud: { enabled: true, endpoint: 'https://cloud.example.com', apiKey: '...' },
+  static: { hubAddress: '192.168.1.100:3000' },
+  probing: { enabled: true, intervalMs: 10000, timeoutMs: 2000 },
+};
+```
+
+### Network Events
+
+Events emitted by the network manager:
+
+```typescript
+import type { NetworkEventMap } from '@rljson/network';
+import { networkEventNames } from '@rljson/network';
+
+// Event names: 'topology-changed', 'role-changed', 'hub-changed',
+//              'peer-joined', 'peer-left'
+```
+
+## NodeIdentity
+
+Persistent node identity — generates a UUID on first run, reads the same
+UUID on subsequent runs (same machine = same identity):
+
+```typescript
+import { NodeIdentity } from '@rljson/network';
+
+const identity = await NodeIdentity.create({
+  domain: 'office-sync',
+  port: 3000,
+  // identityDir: '/custom/path',  // Default: ~/.rljson-network/
+});
+
+console.log(identity.nodeId);    // Persistent UUID
+console.log(identity.hostname);  // Machine hostname
+console.log(identity.localIps);  // ['192.168.1.42']
+
+const info = identity.toNodeInfo(); // Plain NodeInfo object
+```
+
+## Discovery Layers
+
+All layers implement the `DiscoveryLayer` interface:
+
+```typescript
+import type { DiscoveryLayer } from '@rljson/network';
+// Methods: start(), stop(), isActive(), getPeers(), getAssignedHub(), on(), off()
+```
+
+### ManualLayer
+
+Always-present manual override. Cannot be disabled:
+
+```typescript
+import { ManualLayer } from '@rljson/network';
+
+const manual = new ManualLayer();
+await manual.start(identity);
+
+manual.assignHub('specific-node-id');   // Force a hub
+manual.clearOverride();                 // Return to cascade
+```
+
+### BroadcastLayer (Try 1)
+
+UDP broadcast discovery — zero-config LAN peer detection:
+
+```typescript
+import { BroadcastLayer, defaultCreateUdpSocket } from '@rljson/network';
+import type { BroadcastConfig, BroadcastLayerDeps } from '@rljson/network';
+
+const config: BroadcastConfig = {
+  enabled: true,
+  port: 41234,
+  intervalMs: 5000,   // How often to broadcast
+  timeoutMs: 15000,   // Remove peer after silence
+};
+
+const layer = new BroadcastLayer(config);
+const started = await layer.start(identity);
+// started = true if UDP broadcast is available (self-test passed)
+// started = false if broadcast blocked, disabled, or bind failed
+
+layer.on('peer-discovered', (peer) => console.log('Found:', peer.nodeId));
+layer.on('peer-lost', (nodeId) => console.log('Lost:', nodeId));
+
+console.log(layer.getPeers());        // Currently discovered peers
+console.log(layer.getAssignedHub());   // Always null (broadcast doesn't assign)
+
+await layer.stop();
+```
+
+For testing, inject a mock socket factory:
+
+```typescript
+import type { UdpSocket, CreateUdpSocket } from '@rljson/network';
+
+const deps: BroadcastLayerDeps = {
+  createSocket: myMockSocketFactory,
+  selfTestTimeoutMs: 50,
+};
+const layer = new BroadcastLayer(config, deps);
+```
+
+### CloudLayer (Try 2)
+
+REST-based cloud discovery fallback. The cloud service has the full picture
+and **dictates** the hub (unlike broadcast, which uses local election):
+
+```typescript
+import { CloudLayer, defaultCreateCloudHttpClient } from '@rljson/network';
+import type { CloudConfig, CloudLayerDeps, CloudHttpClient } from '@rljson/network';
+
+const config: CloudConfig = {
+  enabled: true,
+  endpoint: 'https://cloud.example.com',
+  apiKey: 'my-api-key',          // Optional Bearer token
+  pollIntervalMs: 30000,         // How often to poll (default: 30000)
+};
+
+const layer = new CloudLayer(config);
+const started = await layer.start(identity);
+// started = true if enabled + endpoint present + registration succeeded
+// started = false if disabled or no endpoint
+
+layer.on('peer-discovered', (peer) => console.log('Cloud peer:', peer.nodeId));
+layer.on('hub-assigned', (hubId) => console.log('Cloud assigned hub:', hubId));
+
+console.log(layer.getPeers());        // Peers from cloud
+console.log(layer.getAssignedHub());  // Hub dictated by cloud, or null
+
+// Report local probe results to cloud (cloud uses these for hub decisions)
+await layer.reportProbes(probes);
+
+await layer.stop();
+```
+
+For testing, inject a mock HTTP client:
+
+```typescript
+import type { CloudHttpClient, CloudLayerDeps } from '@rljson/network';
+
+const mockClient: CloudHttpClient = {
+  register: async () => ({ peers: [], assignedHub: null }),
+  poll: async () => ({ peers: [], assignedHub: null }),
+  reportProbes: async () => {},
+};
+
+const deps: CloudLayerDeps = { createHttpClient: () => mockClient };
+const layer = new CloudLayer(config, deps);
+```
+
+### StaticLayer
+
+Last-resort fallback — reads a hardcoded hub address from config:
+
+```typescript
+import { StaticLayer } from '@rljson/network';
+
+const staticLayer = new StaticLayer({ hubAddress: '192.168.1.100:3000' });
+const started = await staticLayer.start(identity);
+// started = true (has config), creates synthetic peer for hub
+
+const noConfig = new StaticLayer();
+const started2 = await noConfig.start(identity);
+// started2 = false (no hubAddress configured)
+```
+
+## PeerTable
+
+Merged view of all peers from all discovery layers. Deduplicates by nodeId:
+
+```typescript
+import { PeerTable } from '@rljson/network';
+
+const table = new PeerTable();
+table.setSelfId(identity.nodeId);
+
+table.attachLayer(staticLayer);    // Import peers + subscribe to events
+table.attachLayer(manualLayer);
+
+table.on('peer-joined', (peer) => console.log('New peer:', peer.nodeId));
+table.on('peer-left', (nodeId) => console.log('Lost peer:', nodeId));
+
+console.log(table.getPeers());    // All known peers
+console.log(table.size);          // Number of peers
+```
+
+## NetworkManager
+
+Central orchestrator — starts layers, merges peer tables, applies cascade
+logic, and emits topology events:
+
+```typescript
+import { NetworkManager, defaultNetworkConfig } from '@rljson/network';
+
+const config = {
+  ...defaultNetworkConfig('office-sync', 3000),
+  static: { hubAddress: '192.168.1.100:3000' },
+};
+const manager = new NetworkManager(config);
+
+manager.on('topology-changed', (e) => {
+  console.log('Topology:', e.topology.myRole, e.topology.formedBy);
+});
+manager.on('role-changed', (e) => {
+  console.log(`Role: ${e.previous} → ${e.current}`);
+});
+manager.on('hub-changed', (e) => {
+  console.log(`Hub: ${e.previousHub} → ${e.currentHub}`);
+});
+
+await manager.start();
+
+const topology = manager.getTopology();
+// { myRole: 'client', formedBy: 'static', hubAddress: '192.168.1.100:3000', ... }
+
+// Manual override supersedes cascade
+manager.assignHub('custom-hub-id');
+// Now formedBy: 'manual'
+
+// Revert to cascade
+manager.clearOverride();
+// Back to formedBy: 'static'
+
+await manager.stop();
+```
+
+### Hub Decision Cascade
+
+The `NetworkManager` evaluates hub assignment in this order:
+
+1. **Manual override** → human knows best
+2. **Election via probing** → probes determine reachable peers, election picks hub
+   - `formedBy: 'broadcast'` when broadcast layer is active with peers
+   - `formedBy: 'election'` otherwise
+3. **Cloud assignment** → cloud dictates hub (has the full picture)
+4. **Static config** → last resort
+5. **Nothing** → `myRole = 'unassigned'`
+
+## Hub Election
+
+Pure deterministic election algorithm — no I/O, no side effects:
+
+```typescript
+import { electHub } from '@rljson/network';
+import type { ElectionResult } from '@rljson/network';
+
+const candidates = [
+  { nodeId: 'node-a', host: '10.0.0.1', port: 3000, ... startedAt: 1000 },
+  { nodeId: 'node-b', host: '10.0.0.2', port: 3000, ... startedAt: 900 },
+];
+const probes = [
+  { fromNodeId: 'self', toNodeId: 'node-a', reachable: true, latencyMs: 5, measuredAt: Date.now() },
+  { fromNodeId: 'self', toNodeId: 'node-b', reachable: true, latencyMs: 3, measuredAt: Date.now() },
+];
+
+const result: ElectionResult = electHub(candidates, probes, null, 'self');
+// result.hubId = 'node-b' (earliest startedAt)
+// result.reason = 'earliest-start'
+```
+
+Election rules:
+1. Filter candidates to reachable peers only (self is always reachable)
+2. **Incumbent advantage**: keep current hub if still reachable
+3. **Earliest `startedAt`** wins among reachable candidates
+4. **Tiebreaker**: lexicographic `nodeId` comparison
+
+## Probing
+
+### PeerProber
+
+Real TCP connect probe — tests whether a peer is reachable:
+
+```typescript
+import { probePeer } from '@rljson/network';
+
+const probe = await probePeer('192.168.1.42', 3000, 'my-node', 'peer-node');
+// { reachable: true, latencyMs: 2.45, fromNodeId: 'my-node', toNodeId: 'peer-node', ... }
+
+// With custom timeout
+const probe2 = await probePeer('10.0.0.1', 3000, 'my-node', 'remote', { timeoutMs: 500 });
+```
+
+### ProbeScheduler
+
+Periodically probes all known peers and detects state changes:
+
+```typescript
+import { ProbeScheduler } from '@rljson/network';
+
+const scheduler = new ProbeScheduler({
+  intervalMs: 5000,
+  timeoutMs: 2000,
+  failThreshold: 3,   // Consecutive failures before 'unreachable' (default: 3)
+});
+scheduler.start('my-node-id');
+scheduler.setPeers([peerA, peerB]); // NodeInfo[]
+
+scheduler.on('probes-updated', (probes) => {
+  console.log('All probe results:', probes);
+});
+scheduler.on('peer-unreachable', (nodeId, probe) => {
+  console.log(`${nodeId} went down!`);
+});
+scheduler.on('peer-reachable', (nodeId, probe) => {
+  console.log(`${nodeId} came back!`);
+});
+
+// Manual single cycle (useful for tests)
+const results = await scheduler.runOnce();
+
+scheduler.stop();
+```
+
+The `NetworkManager` creates and manages a `ProbeScheduler` internally.
+Access it via `manager.getProbeScheduler()` for advanced use.
+
+**Flap dampening**: A peer must fail `failThreshold` consecutive probes
+(default: 3) before being declared unreachable. A single success resets
+the counter immediately. This prevents flapping on transient network glitches.
+
+## Example
+
+[src/example.ts](src/example.ts)

package/dist/README.trouble.md

@@ -0,0 +1,23 @@
+<!--
+@license
+Copyright (c) 2025 Rljson
+
+Use of this source code is governed by terms that can be
+found in the LICENSE file in the root of this package.
+-->
+
+# Trouble shooting
+
+## Table of contents <!-- omit in toc -->
+
+- [Vscode Windows: Debugging is not working](#vscode-windows-debugging-is-not-working)
+
+## Vscode Windows: Debugging is not working
+
+Date: 2025-03-08
+
+⚠️ IMPORTANT: On Windows, please check out the repo on drive C. There is a bug
+in the VS Code Vitest extension (v1.14.4), which prevents test debugging from
+working: <https://github.com/vitest-dev/vscode/issues/548> Please check from
+time to time if the issue has been fixed and remove this note once it is
+resolved.

package/dist/election/hub-election.d.ts

@@ -0,0 +1,28 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { PeerProbe } from '../types/peer-probe.ts';
+/** Result of a hub election */
+export interface ElectionResult {
+    /** The elected hub's nodeId, or null if no candidate qualifies */
+    hubId: NodeId | null;
+    /** Why this hub was chosen */
+    reason: ElectionReason;
+}
+/** Reason for the election outcome */
+export type ElectionReason = 'incumbent' | 'earliest-start' | 'tiebreaker' | 'no-candidates';
+/**
+ * Deterministic hub election algorithm.
+ *
+ * Rules (in priority order):
+ * 1. Filter to reachable peers only (those with a passing probe)
+ * 2. Incumbent advantage — if the current hub is reachable, keep it
+ * 3. Earliest `startedAt` wins
+ * 4. Lexicographic `nodeId` tiebreaker (astronomically rare)
+ *
+ * This is a pure function — no I/O, no side effects.
+ * @param candidates - All known peers (including self)
+ * @param probes - Latest probe results for reachability
+ * @param currentHubId - The current hub's nodeId (null if none)
+ * @param selfId - This node's own nodeId (always considered reachable)
+ * @returns The election result with hubId and reason
+ */
+export declare function electHub(candidates: NodeInfo[], probes: PeerProbe[], currentHubId: NodeId | null, selfId: NodeId): ElectionResult;

package/dist/example.d.ts

@@ -0,0 +1 @@
+export declare const example: () => Promise<void>;

package/dist/identity/node-identity.d.ts

@@ -0,0 +1,52 @@
+import { NetworkInterfaceInfo } from 'node:os';
+import { NodeInfo } from '../types/node-info.ts';
+/**
+ * Parse IPv4 non-internal addresses from network interface data.
+ * @param interfaces - OS network interface data (from os.networkInterfaces())
+ */
+export declare function parseLocalIps(interfaces: NodeJS.Dict<NetworkInterfaceInfo[]>): string[];
+/** Injectable dependencies for NodeIdentity (testing) */
+export interface NodeIdentityDeps {
+    readNodeId: (filePath: string) => Promise<string | null>;
+    writeNodeId: (filePath: string, nodeId: string) => Promise<void>;
+    hostname: () => string;
+    localIps: () => string[];
+    randomUUID: () => string;
+    now: () => number;
+    homedir: () => string;
+}
+/** Default deps using real Node.js APIs */
+export declare function defaultNodeIdentityDeps(): NodeIdentityDeps;
+/** Options for creating a NodeIdentity */
+export interface CreateNodeIdentityOptions {
+    /** Network domain — which group of nodes discover each other */
+    domain: string;
+    /** Port this node listens on when hub */
+    port: number;
+    /** Where to persist nodeId (default: ~/.rljson-network/) */
+    identityDir?: string;
+    /** Override dependencies for testing */
+    deps?: Partial<NodeIdentityDeps>;
+}
+/**
+ * Represents this node's identity in the network.
+ *
+ * On first run, generates a persistent UUID stored on disk.
+ * On subsequent runs, reads the same UUID — same machine = same identity.
+ */
+export declare class NodeIdentity {
+    readonly nodeId: string;
+    readonly hostname: string;
+    readonly localIps: string[];
+    readonly domain: string;
+    readonly port: number;
+    readonly startedAt: number;
+    constructor(info: NodeInfo);
+    /** Convert to a plain NodeInfo data object */
+    toNodeInfo(): NodeInfo;
+    /**
+     * Create a NodeIdentity, loading or generating a persistent UUID.
+     * @param options - Configuration and optional dependency overrides
+     */
+    static create(options: CreateNodeIdentityOptions): Promise<NodeIdentity>;
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export type { NodeId, NodeInfo } from './types/node-info.ts';
+export { exampleNodeInfo } from './types/node-info.ts';
+export type { PeerProbe } from './types/peer-probe.ts';
+export { examplePeerProbe } from './types/peer-probe.ts';
+export type { NodeRole, FormedBy, NetworkTopology, } from './types/network-topology.ts';
+export { nodeRoles, formedByValues, exampleNetworkTopology, } from './types/network-topology.ts';
+export type { BroadcastConfig, CloudConfig, StaticConfig, ProbingConfig, NetworkConfig, } from './types/network-config.ts';
+export { defaultNetworkConfig } from './types/network-config.ts';
+export type { TopologyChangedEvent, RoleChangedEvent, HubChangedEvent, NetworkEventMap, NetworkEventName, } from './types/network-events.ts';
+export { networkEventNames, exampleTopologyChangedEvent, exampleRoleChangedEvent, exampleHubChangedEvent, } from './types/network-events.ts';
+export type { NodeIdentityDeps, CreateNodeIdentityOptions, } from './identity/node-identity.ts';
+export { NodeIdentity, parseLocalIps, defaultNodeIdentityDeps, } from './identity/node-identity.ts';
+export type { DiscoveryLayer, DiscoveryLayerEvents, DiscoveryLayerEventName, } from './layers/discovery-layer.ts';
+export type { UdpSocket, RemoteInfo, CreateUdpSocket, BroadcastLayerDeps, } from './layers/broadcast-layer.ts';
+export { BroadcastLayer, defaultCreateUdpSocket, } from './layers/broadcast-layer.ts';
+export type { CloudHttpClient, CloudPeerListResponse, CreateCloudHttpClient, CloudLayerDeps, } from './layers/cloud-layer.ts';
+export { CloudLayer, defaultCreateCloudHttpClient, } from './layers/cloud-layer.ts';
+export { ManualLayer } from './layers/manual-layer.ts';
+export { StaticLayer } from './layers/static-layer.ts';
+export type { PeerTableEvents } from './peer-table.ts';
+export { PeerTable } from './peer-table.ts';
+export type { ElectionResult, ElectionReason, } from './election/hub-election.ts';
+export { electHub } from './election/hub-election.ts';
+export type { ProbeOptions } from './probing/peer-prober.ts';
+export { probePeer } from './probing/peer-prober.ts';
+export type { ProbeFn, ProbeSchedulerEvents, ProbeSchedulerEventName, ProbeSchedulerOptions, } from './probing/probe-scheduler.ts';
+export { ProbeScheduler } from './probing/probe-scheduler.ts';
+export type { NetworkManagerEvents, NetworkManagerEventName, NetworkManagerOptions, } from './network-manager.ts';
+export { NetworkManager } from './network-manager.ts';

package/dist/layers/broadcast-layer.d.ts

@@ -0,0 +1,132 @@
+import { NodeId, NodeInfo } from '../types/node-info.ts';
+import { BroadcastConfig } from '../types/network-config.ts';
+import { NodeIdentity } from '../identity/node-identity.ts';
+import { DiscoveryLayer, DiscoveryLayerEventName, DiscoveryLayerEvents } from './discovery-layer.ts';
+/** Remote info about a received UDP packet */
+export interface RemoteInfo {
+    address: string;
+    port: number;
+}
+/** Abstraction over a UDP socket for testability */
+export interface UdpSocket {
+    /** Bind the socket to a port */
+    bind(port: number): Promise<void>;
+    /** Send data via UDP to a target port and address */
+    send(data: Buffer, port: number, address: string): Promise<void>;
+    /** Register a message handler */
+    onMessage(handler: (msg: Buffer, rinfo: RemoteInfo) => void): void;
+    /** Enable broadcasting on this socket */
+    setBroadcast(flag: boolean): void;
+    /** Close the socket */
+    close(): Promise<void>;
+}
+/** Factory function to create a UDP socket */
+export type CreateUdpSocket = () => UdpSocket;
+/**
+ * Create a real UDP socket using node:dgram.
+ * @returns A UdpSocket backed by a real dgram socket
+ */
+export declare function defaultCreateUdpSocket(): UdpSocket;
+/** Injectable dependencies for BroadcastLayer (testing) */
+export interface BroadcastLayerDeps {
+    /** Custom socket factory — defaults to real dgram */
+    createSocket?: CreateUdpSocket;
+    /** Self-test timeout in ms — defaults to 2000 */
+    selfTestTimeoutMs?: number;
+}
+/**
+ * UDP broadcast discovery layer — primary automatic discovery (Try 1).
+ *
+ * Periodically broadcasts this node's info as a JSON packet on a configurable
+ * UDP port. Listens for other nodes' broadcasts and maintains a peer table
+ * with timeout-based cleanup.
+ *
+ * On startup, performs a self-test by sending a broadcast and checking for
+ * loopback reception. If broadcast is blocked on the network, start() returns
+ * false and the NetworkManager falls through to the next layer.
+ *
+ * BroadcastLayer does NOT assign a hub — it only discovers peers.
+ * Hub election is handled by the NetworkManager via the election algorithm.
+ */
+export declare class BroadcastLayer implements DiscoveryLayer {
+    private readonly _config?;
+    readonly name = "broadcast";
+    private _active;
+    private _socket;
+    private _identity;
+    private _broadcastTimer;
+    private _timeoutTimer;
+    private _selfTestCallback;
+    private _peers;
+    private _listeners;
+    private readonly _createSocket;
+    private readonly _selfTestTimeoutMs;
+    /**
+     * Create a BroadcastLayer.
+     * @param _config - Broadcast configuration (port, interval, timeout)
+     * @param deps - Injectable dependencies for testing
+     */
+    constructor(_config?: BroadcastConfig | undefined, deps?: BroadcastLayerDeps);
+    /**
+     * 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
+     */
+    start(identity: NodeIdentity): Promise<boolean>;
+    /** Stop the layer and clean up resources */
+    stop(): Promise<void>;
+    /** Whether this layer is currently active */
+    isActive(): boolean;
+    /** Get all currently known peers from broadcast discovery */
+    getPeers(): NodeInfo[];
+    /**
+     * Broadcast does NOT assign a hub — hub is elected by NetworkManager.
+     * Always returns null.
+     */
+    getAssignedHub(): NodeId | null;
+    /**
+     * Subscribe to layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    on<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * Unsubscribe from layer events.
+     * @param event - Event name
+     * @param cb - Callback
+     */
+    off<E extends DiscoveryLayerEventName>(event: E, cb: DiscoveryLayerEvents[E]): void;
+    /**
+     * 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
+     */
+    private _selfTest;
+    /**
+     * Send a broadcast packet containing this node's info.
+     * @param port - The UDP port to broadcast on
+     */
+    private _sendBroadcast;
+    /**
+     * Handle an incoming broadcast message.
+     * @param msg - Raw UDP message
+     * @param _rinfo - Remote address info (unused — we use packet content)
+     */
+    private _handleMessage;
+    /**
+     * Check for timed-out peers and remove them.
+     * @param timeoutMs - Maximum silence period before declaring peer lost
+     */
+    private _checkTimeouts;
+    /**
+     * Emit a typed event to all registered listeners.
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    private _emit;
+}