threadforge 0.1.1 → 0.2.1

package/src/core/WorkerChannelManager.js

@@ -1,879 +0,0 @@
-import net from "node:net";
-import fs from "node:fs";
-import path from "node:path";
-import { randomBytes, randomUUID, createHmac, timingSafeEqual } from "node:crypto";
-
-/**
- * WorkerChannelManager — Unix Domain Socket Mesh (Worker Side)
- *
- * Each worker runs a UDS server. When it receives the socket registry
- * from the supervisor, it connects directly to other workers' UDS servers.
- *
- * Protocol: Length-prefixed JSON frames
- *   [4 bytes: message length (UInt32BE)][JSON payload]
- *
- * This gives us:
- *   - Direct worker-to-worker communication (no supervisor in the path)
- *   - Full duplex (both sides can send at any time)
- *   - No serialization bottleneck at the supervisor
- *   - Automatic reconnection on socket errors
- */
-/** Maximum UDS message size: 16 MB */
-const MAX_UDS_MESSAGE = 16 * 1024 * 1024;
-
-/** Maximum number of pending requests before rejecting new ones */
-const MAX_PENDING_REQUESTS = 10000;
-
-/** Maximum socket write buffer size before refusing new writes (4 MB) */
-const MAX_WRITE_BUFFER = 4 * 1024 * 1024;
-
-/** Maximum parse errors before destroying a socket */
-const MAX_PARSE_ERRORS = 3;
-
-/** Handshake timeout for server-side inbound connections (ms) */
-const HANDSHAKE_TIMEOUT = 5000;
-
-/** Maximum reconnection attempts before giving up on a peer */
-const MAX_RECONNECT_ATTEMPTS = 10;
-
-
-/**
- * Create a reusable frame parser for length-prefixed JSON frames.
- * Encapsulates the buffer-list pattern to avoid O(n^2) Buffer.concat on every chunk.
- * @param {function(object): void} onFrame - called with each parsed JSON message
- * @param {string} serviceName - for error logging
- * @param {net.Socket} socket - socket to destroy on protocol errors
- * @returns {function(Buffer): void} data event handler
- */
-function createFrameParser(onFrame, serviceName, socket) {
-  const chunks = [];
-  let totalLength = 0;
-  let buffer = Buffer.alloc(0);
-  let parseErrorCount = 0;
-
-  return (chunk) => {
-    // Reject oversized individual chunks before any allocation
-    if (chunk.length > MAX_UDS_MESSAGE + 4) {
-      parseErrorCount++;
-      if (parseErrorCount >= MAX_PARSE_ERRORS) {
-        console.error(`[${serviceName}] UDS chunk too large (${chunk.length} bytes), ${parseErrorCount} parse errors — destroying connection`);
-        chunks.length = 0;
-        totalLength = 0;
-        buffer = Buffer.alloc(0);
-        socket.destroy();
-      } else {
-        console.warn(`[${serviceName}] UDS chunk too large (${chunk.length} bytes), skipping (error ${parseErrorCount}/${MAX_PARSE_ERRORS})`);
-      }
-      return;
-    }
-
-    // Guard against buffer overflow (buffer + pending chunks + new chunk)
-    if (buffer.length + totalLength + chunk.length > MAX_UDS_MESSAGE + 4) {
-      parseErrorCount++;
-      if (parseErrorCount >= MAX_PARSE_ERRORS) {
-        console.error(`[${serviceName}] UDS buffer overflow detected, ${parseErrorCount} parse errors — destroying connection`);
-        chunks.length = 0;
-        totalLength = 0;
-        buffer = Buffer.alloc(0);
-        socket.destroy();
-      } else {
-        console.warn(`[${serviceName}] UDS buffer overflow detected, skipping frame (error ${parseErrorCount}/${MAX_PARSE_ERRORS})`);
-        // Reset buffer to recover
-        chunks.length = 0;
-        totalLength = 0;
-        buffer = Buffer.alloc(0);
-      }
-      return;
-    }
-
-    chunks.push(chunk);
-    totalLength += chunk.length;
-
-    // Only concatenate when we might have a complete frame
-    if (buffer.length + totalLength < 4) return;
-
-    // Merge chunks into buffer for frame parsing
-    if (chunks.length > 0) {
-      buffer = Buffer.concat([buffer, ...chunks]);
-      chunks.length = 0;
-      totalLength = 0;
-    }
-
-    // Parse length-prefixed frames
-    while (buffer.length >= 4) {
-      const msgLen = buffer.readUInt32BE(0);
-
-      if (msgLen > MAX_UDS_MESSAGE) {
-        parseErrorCount++;
-        if (parseErrorCount >= MAX_PARSE_ERRORS) {
-          console.error(`[${serviceName}] UDS message too large (${msgLen} bytes), ${parseErrorCount} parse errors — destroying socket`);
-          buffer = Buffer.alloc(0);
-          socket.destroy();
-          return;
-        }
-        console.warn(`[${serviceName}] UDS message too large (${msgLen} bytes), skipping frame (error ${parseErrorCount}/${MAX_PARSE_ERRORS})`);
-        // Skip past the 4-byte length prefix to try to recover
-        buffer = buffer.subarray(4);
-        continue;
-      }
-
-      if (buffer.length < 4 + msgLen) break; // wait for more data
-
-      const msgBuf = buffer.subarray(4, 4 + msgLen);
-      buffer = buffer.subarray(4 + msgLen);
-
-      try {
-        // COR-C2: Reviver prevents prototype pollution via __proto__/constructor/prototype keys
-        const msg = JSON.parse(msgBuf.toString(), (key, value) => {
-          if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
-          return value;
-        });
-        onFrame(msg);
-      } catch (err) {
-        console.error(`[${serviceName}] Failed to parse UDS message:`, err.message);
-      }
-    }
-  };
-}
-
-export class WorkerChannelManager {
-  /**
-   * @param {string} serviceName
-   * @param {number} workerId
-   * @param {object} [options]
-   * @param {string[]} [options.channels] - Service names this worker needs to communicate with (P1: dependency filtering)
-   * @param {Function} [options.onChannelDead] - Called when a channel permanently fails reconnection
-   */
-  constructor(serviceName, workerId, options = {}) {
-    this.serviceName = serviceName;
-    this.workerId = workerId;
-
-    /**
-     * P1: Set of service names this worker is allowed to connect to.
-     * If null, connects to everything (legacy behavior).
-     * @type {Set<string>|null}
-     */
-    this._dependencies = options.channels ? new Set(options.channels) : null;
-
-    /** @type {Function|null} Called with (key, attempts) when a channel exhausts reconnection attempts */
-    this._onChannelDead = options.onChannelDead ?? null;
-
-    /** @type {net.Server|null} */
-    this._server = null;
-
-    /** @type {string|null} */
-    this._socketPath = null;
-
-    /**
-     * Outbound connections to other workers.
-     * Key: "serviceName:workerId"
-     * @type {Map<string, net.Socket>}
-     */
-    this.outbound = new Map();
-
-    /**
-     * Inbound connections from other workers.
-     * Key: "serviceName:workerId" (identified via handshake)
-     * @type {Map<string, net.Socket>}
-     */
-    this.inbound = new Map();
-
-    /**
-     * Service name → array of connection keys for round-robin.
-     * @type {Map<string, string[]>}
-     */
-    this.serviceConnections = new Map();
-
-    /** @type {Map<string, number>} */
-    this.rrIndex = new Map();
-
-    /** @type {Map<string, {resolve: Function, reject: Function, timer: NodeJS.Timeout}>} */
-    this.pendingRequests = new Map();
-
-    this.requestCounter = 0;
-
-    /** Worker ID for unique request IDs; falls back to process.pid */
-    this._workerId = workerId ?? process.pid;
-
-    /** @type {Function|null} */
-    this.onMessage = null;
-
-    /** @type {Function|null} */
-    this.onRequest = null;
-
-    /** @type {Function|null} - fallback to supervisor IPC */
-    this._supervisorSend = null;
-
-    /** @type {Object} current socket registry from supervisor */
-    this._registry = {};
-
-    /** @type {Map<string, number>} per-peer reconnect attempt counters */
-    this._reconnectAttempts = new Map();
-
-    /** @type {Map<string, NodeJS.Timeout>} reconnect timer refs for cleanup */
-    this._reconnectTimers = new Map();
-
-    /** P19: Reverse map from socket → key for O(1) lookup */
-    this._socketKeyMap = new Map();
-
-    /** @type {number} counter of backpressure events on send() */
-    this.backpressureEvents = 0;
-  }
-
-  /**
-   * Initialize — set up supervisor IPC listener.
-   */
-  init(supervisorSend) {
-    this._supervisorSend = supervisorSend;
-
-    process.on("message", (msg) => {
-      if (!msg || !msg.type) return;
-
-      switch (msg.type) {
-        case "forge:init-socket":
-          this._startServer(msg.socketDir, msg.serviceName, msg.workerId);
-          break;
-
-        case "forge:socket-registry":
-          this._updateRegistry(msg.registry);
-          break;
-
-        case "forge:health-check":
-          supervisorSend({
-            type: "forge:health-response",
-            timestamp: msg.timestamp,
-            uptime: process.uptime(),
-            memory: process.memoryUsage(),
-            pid: process.pid,
-            directConnections: this.outbound.size,
-          });
-          break;
-      }
-    });
-  }
-
-  /**
-   * Start our UDS server so other workers can connect to us.
-   */
-  _startServer(socketDir, serviceName, workerId) {
-    // One channel manager exists per service in a colocated worker process.
-    // Ignore init messages for sibling services; each sibling manager will
-    // start its own socket server when it receives its matching message.
-    if (serviceName !== this.serviceName) return;
-    if (this._server) return; // already started
-
-    this._socketPath = path.join(socketDir, `${serviceName}-${workerId}.sock`);
-
-    this._server = net.createServer((socket) => {
-      // A7: Start handshake timeout — close if no handshake within HANDSHAKE_TIMEOUT
-      let handshakeCompleted = false;
-      const handshakeTimer = setTimeout(() => {
-        if (!handshakeCompleted) {
-          console.warn(`[${this.serviceName}] Inbound handshake timeout — closing socket`);
-          socket.destroy();
-        }
-      }, HANDSHAKE_TIMEOUT);
-      handshakeTimer.unref();
-
-      // Inbound connection from another worker — use shared frame parser
-      const onData = createFrameParser(
-        (msg) => {
-          // A7: Clear handshake timer on handshake message
-          if (msg.type === 'forge:handshake' && !handshakeCompleted) {
-            handshakeCompleted = true;
-            clearTimeout(handshakeTimer);
-          }
-          this._handleIncomingMessage(socket, msg);
-        },
-        this.serviceName,
-        socket,
-      );
-
-      socket.on("data", onData);
-
-      socket.on("error", () => {
-        clearTimeout(handshakeTimer);
-      });
-      socket.on("close", () => {
-        clearTimeout(handshakeTimer);
-        // Remove from inbound
-        for (const [key, s] of this.inbound) {
-          if (s === socket) {
-            this.inbound.delete(key);
-            break;
-          }
-        }
-      });
-    });
-
-    this._server.listen(this._socketPath, () => {
-      // Tell supervisor we're ready
-      this._supervisorSend({
-        type: "forge:socket-ready",
-        socketPath: this._socketPath,
-        serviceName,
-        workerId,
-      });
-    });
-
-    this._server.on("error", (err) => {
-      if (err.code === "EADDRINUSE") {
-        // Stale socket file — unlink and retry once
-        try {
-          fs.unlinkSync(this._socketPath);
-        } catch {}
-        this._server.listen(this._socketPath, () => {
-          this._supervisorSend({
-            type: "forge:socket-ready",
-            socketPath: this._socketPath,
-            serviceName,
-            workerId,
-          });
-        });
-      } else {
-        console.error(`[${this.serviceName}] UDS server error:`, err.message);
-      }
-    });
-  }
-
-  /**
-   * Update our knowledge of the socket registry and connect to new peers.
-   */
-  _updateRegistry(registry) {
-    this._registry = registry;
-
-    const myKey = `${this.serviceName}:${this.workerId}`;
-
-    for (const [key, socketPath] of Object.entries(registry)) {
-      if (key === myKey) continue; // don't connect to ourselves
-      if (this.outbound.has(key)) continue; // already connected
-
-      // P1: Only connect to services in our dependency list (if specified)
-      if (this._dependencies) {
-        const [svcName] = key.split(":");
-        if (!this._dependencies.has(svcName)) {
-          continue;
-        }
-      }
-
-      this._connectTo(key, socketPath);
-    }
-  }
-
-  /**
-   * Establish an outbound connection to another worker's UDS server.
-   */
-  _connectTo(key, socketPath) {
-    const socket = net.createConnection(socketPath);
-    let handshakeTimer = null;
-    let dataReceived = false;
-
-    socket.on("connect", () => {
-      this.outbound.set(key, socket);
-      this._socketKeyMap.set(socket, key); // P19: O(1) reverse lookup
-      this._reconnectAttempts.set(key, 0);
-
-      // CR-IPC-13: Start handshake timeout — destroy if no handshake ack within 5s
-      handshakeTimer = setTimeout(() => {
-        if (!dataReceived) {
-          console.warn(`[${this.serviceName}] Handshake timeout for ${key}, destroying socket`);
-          socket.destroy();
-          this.outbound.delete(key);
-        }
-      }, 5000);
-      handshakeTimer.unref();
-
-      // Track service → connection keys for round-robin
-      const [svcName] = key.split(":");
-      if (!this.serviceConnections.has(svcName)) {
-        this.serviceConnections.set(svcName, []);
-      }
-      const keys = this.serviceConnections.get(svcName);
-      if (!keys.includes(key)) keys.push(key);
-
-      // Handshake: tell the other side who we are
-      const handshake = {
-        type: "forge:handshake",
-        from: this.serviceName,
-        fromWorkerId: this.workerId,
-      };
-      const clusterSecret = process.env.FORGE_CLUSTER_SECRET;
-      if (clusterSecret) {
-        handshake.hmac = createHmac('sha256', clusterSecret)
-          .update(`${this.serviceName}:${this.workerId}`)
-          .digest('hex');
-      }
-      this._sendFrame(socket, handshake);
-    });
-
-    // Outbound connection — use shared frame parser
-    const onData = createFrameParser(
-      (msg) => this._handleIncomingMessage(socket, msg),
-      this.serviceName,
-      socket,
-    );
-
-    socket.on("data", (chunk) => {
-      // CR-IPC-13: Clear handshake timeout on first data
-      if (!dataReceived) {
-        dataReceived = true;
-        if (handshakeTimer) {
-          clearTimeout(handshakeTimer);
-          handshakeTimer = null;
-        }
-      }
-      onData(chunk);
-    });
-
-    socket.on("error", () => {
-      if (handshakeTimer) { clearTimeout(handshakeTimer); handshakeTimer = null; }
-      this.outbound.delete(key);
-      this._socketKeyMap.delete(socket); // P19
-      const [svcName] = key.split(":");
-      const keys = this.serviceConnections.get(svcName);
-      if (keys) {
-        const idx = keys.indexOf(key);
-        if (idx !== -1) keys.splice(idx, 1);
-      }
-      // C2: Reject orphaned pending requests for this dead socket
-      this._rejectPendingForSocket(key);
-    });
-
-    socket.on("close", () => {
-      this.outbound.delete(key);
-      this._socketKeyMap.delete(socket); // P19
-      const [svcName] = key.split(":");
-      const keys = this.serviceConnections.get(svcName);
-      if (keys) {
-        const idx = keys.indexOf(key);
-        if (idx !== -1) keys.splice(idx, 1);
-      }
-      // C2: Reject orphaned pending requests for this dead socket
-      this._rejectPendingForSocket(key);
-
-      // A13: Stop retrying after MAX_RECONNECT_ATTEMPTS
-      const existingTimer = this._reconnectTimers.get(key);
-      if (existingTimer) clearTimeout(existingTimer);
-      const attempts = this._reconnectAttempts.get(key) ?? 0;
-      if (attempts >= MAX_RECONNECT_ATTEMPTS) {
-        console.error(`[${this.serviceName}] Channel to ${key} permanently failed after ${attempts} reconnection attempts`);
-        this._reconnectAttempts.delete(key);
-        this._reconnectTimers.delete(key);
-        if (this._onChannelDead) {
-          this._onChannelDead(key, attempts);
-        }
-        return;
-      }
-
-      // Attempt reconnect with exponential backoff
-      this._reconnectAttempts.set(key, attempts + 1);
-      const baseDelay = Math.min(60000, 1000 * 2 ** attempts);
-      const delay = baseDelay + Math.random() * 1000;
-      const timer = setTimeout(() => {
-        this._reconnectTimers.delete(key);
-        if (this._registry[key] && !this.outbound.has(key)) {
-          this._connectTo(key, this._registry[key]);
-        }
-      }, delay);
-      timer.unref();
-      this._reconnectTimers.set(key, timer);
-    });
-  }
-
-  /**
-   * Send a length-prefixed JSON frame over a socket.
-   * P6: Buffer.from(json) avoids double-scan of the string.
-   * @returns {boolean} true if the write was accepted into the kernel buffer
-   */
-  _sendFrame(socket, msg) {
-    // CR-IPC-4: Reject when buffer full — throw so callers can back off
-    if (socket.writableLength > MAX_WRITE_BUFFER) {
-      const key = this._socketKey(socket);
-      throw new Error(`IPC write buffer full for ${key} — receiver too slow`);
-    }
-    // P6: Buffer.from gives us the buffer directly — byteLength = buf.length, no re-scan
-    const json = JSON.stringify(msg);
-    const body = Buffer.from(json);
-    const frame = Buffer.allocUnsafe(4 + body.length);
-    frame.writeUInt32BE(body.length, 0);
-    body.copy(frame, 4);
-    const ok = socket.write(frame);
-    if (!ok && !socket._drainWarned) {
-      socket._drainWarned = true;
-      socket.once("drain", () => { socket._drainWarned = false; });
-      console.warn(`[${this.serviceName}] UDS write buffer full, waiting for drain`);
-    }
-    return ok;
-  }
-
-  /**
-   * Send a pre-built frame buffer over a socket (for broadcast optimization).
-   * P6: Serialize once, send to all recipients.
-   * @returns {boolean}
-   */
-  _sendRawFrame(socket, frameBuffer) {
-    if (socket.writableLength > MAX_WRITE_BUFFER) {
-      const key = this._socketKey(socket);
-      throw new Error(`IPC write buffer full for ${key} — receiver too slow`);
-    }
-    const ok = socket.write(frameBuffer);
-    if (!ok && !socket._drainWarned) {
-      socket._drainWarned = true;
-      socket.once("drain", () => { socket._drainWarned = false; });
-      console.warn(`[${this.serviceName}] UDS write buffer full, waiting for drain`);
-    }
-    return ok;
-  }
-
-  /**
-   * Build a length-prefixed frame buffer from a message object.
-   * P6: Used by broadcast to serialize once and send to all.
-   */
-  _buildFrame(msg) {
-    const json = JSON.stringify(msg);
-    const body = Buffer.from(json);
-    const frame = Buffer.allocUnsafe(4 + body.length);
-    frame.writeUInt32BE(body.length, 0);
-    body.copy(frame, 4);
-    return frame;
-  }
-
-  /**
-   * Handle a message from another worker (inbound or outbound socket).
-   */
-  _handleIncomingMessage(socket, msg) {
-    switch (msg.type) {
-      case "forge:handshake": {
-        if (!msg.from || typeof msg.from !== 'string') {
-          console.warn(`[${this.serviceName}] Invalid handshake: missing 'from' field`);
-          break;
-        }
-        // S-IPC-1: Verify HMAC if cluster secret is configured
-        const clusterSecret = process.env.FORGE_CLUSTER_SECRET;
-        if (clusterSecret) {
-          const expected = createHmac('sha256', clusterSecret)
-            .update(`${msg.from}:${msg.fromWorkerId}`)
-            .digest('hex');
-          // Wrap in try/catch: if msg.hmac is not valid hex, Buffer.from
-          // produces a different-length buffer and timingSafeEqual throws
-          try {
-            const expectedBuf = Buffer.from(expected, 'hex');
-            const hmacBuf = msg.hmac ? Buffer.from(String(msg.hmac), 'hex') : Buffer.alloc(0);
-            if (hmacBuf.length !== expectedBuf.length || !timingSafeEqual(expectedBuf, hmacBuf)) {
-              throw new Error('HMAC mismatch');
-            }
-          } catch {
-            console.error(`[${this.serviceName}] Handshake HMAC verification failed for ${msg.from}:${msg.fromWorkerId}`);
-            socket.destroy();
-            break;
-          }
-        }
-        const key = `${msg.from}:${msg.fromWorkerId}`;
-        this.inbound.set(key, socket);
-        try {
-          this._sendFrame(socket, {
-            type: "forge:handshake-ack",
-            from: this.serviceName,
-            fromWorkerId: this.workerId,
-          });
-        } catch (err) {
-          console.warn(`[${this.serviceName}] Failed to send handshake ack: ${err.message}`);
-          socket.destroy();
-        }
-        break;
-      }
-
-      case "forge:handshake-ack": {
-        break;
-      }
-
-      case "forge:message": {
-        if (this.onMessage) {
-          this.onMessage(msg.from, msg.payload);
-        }
-        break;
-      }
-
-      case "forge:request": {
-        if (this.onRequest) {
-          Promise.resolve(this.onRequest(msg.from, msg.payload))
-            .then((result) => {
-              try {
-                this._sendFrame(socket, {
-                  type: "forge:response",
-                  requestId: msg.requestId,
-                  payload: result,
-                  error: null,
-                });
-              } catch (sendErr) {
-                console.error(`[${this.serviceName}] Failed to send response: ${sendErr.message}`);
-              }
-            })
-            .catch((err) => {
-              try {
-                this._sendFrame(socket, {
-                  type: "forge:response",
-                  requestId: msg.requestId,
-                  payload: null,
-                  error: { message: err.message, code: err.code, statusCode: err.statusCode },
-                });
-              } catch (sendErr) {
-                console.error(`[${this.serviceName}] Failed to send error response: ${sendErr.message}`);
-              }
-            });
-        }
-        break;
-      }
-
-      case "forge:response": {
-        const pending = this.pendingRequests.get(msg.requestId);
-        if (pending) {
-          clearTimeout(pending.timer);
-          this.pendingRequests.delete(msg.requestId);
-          if (msg.error) {
-            const errObj = typeof msg.error === 'object' ? msg.error : { message: msg.error };
-            const err = new Error(errObj.message);
-            if (errObj.code) err.code = errObj.code;
-            if (errObj.statusCode) err.statusCode = errObj.statusCode;
-            pending.reject(err);
-          } else {
-            pending.resolve(msg.payload);
-          }
-        }
-        break;
-      }
-    }
-  }
-
-  // -- Public API (called by ForgeContext) --
-
-  /**
-   * Send a fire-and-forget message. Direct UDS path if available.
-   */
-  send(target, payload) {
-    const socket = this._pickSocket(target);
-
-    if (socket) {
-      try {
-        const ok = this._sendFrame(socket, {
-          type: "forge:message",
-          from: this.serviceName,
-          payload,
-        });
-        if (!ok) {
-          this.backpressureEvents++;
-          console.warn(`[${this.serviceName}] Backpressure on send() to "${target}" (total: ${this.backpressureEvents})`);
-        }
-      } catch (err) {
-        this.backpressureEvents++;
-        throw err;
-      }
-    } else {
-      // Fallback to supervisor IPC
-      this._supervisorSend({
-        type: "forge:send",
-        target,
-        payload,
-      });
-    }
-  }
-
-  /**
-   * Broadcast to all workers of a target service.
-   */
-  broadcast(target, payload) {
-    const keys = this.serviceConnections.get(target) ?? [];
-
-    if (keys.length > 0) {
-      // P6: Serialize once, send the same buffer to all recipients
-      const frame = this._buildFrame({
-        type: "forge:message",
-        from: this.serviceName,
-        payload,
-      });
-      for (const key of keys) {
-        const socket = this.outbound.get(key);
-        if (socket) {
-          try {
-            this._sendRawFrame(socket, frame);
-          } catch (err) {
-            console.warn(`[${this.serviceName}] Broadcast to ${key} failed: ${err.message}`);
-          }
-        }
-      }
-    } else {
-      this._supervisorSend({
-        type: "forge:broadcast",
-        target,
-        payload,
-      });
-    }
-  }
-
-  /**
-   * Request/response over direct UDS.
-   */
-  request(target, payload, timeoutMs = 5000) {
-    if (this.pendingRequests.size >= MAX_PENDING_REQUESTS) {
-      return Promise.reject(new Error('Too many pending requests'));
-    }
-
-    const socket = this._pickSocket(target);
-    this.requestCounter = (this.requestCounter + 1) % 1_000_000_000;
-    const requestId = `req_${this._workerId}_${randomUUID()}`;
-
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(requestId);
-        reject(new Error(`Request to "${target}" timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      const sKey = socket ? this._socketKey(socket) : null;
-      this.pendingRequests.set(requestId, { resolve, reject, timer, socketKey: sKey });
-
-      try {
-        if (socket) {
-          this._sendFrame(socket, {
-            type: "forge:request",
-            requestId,
-            from: this.serviceName,
-            payload,
-          });
-        } else {
-          this._supervisorSend({
-            type: "forge:request",
-            requestId,
-            target,
-            payload,
-            timeout: timeoutMs,
-          });
-        }
-      } catch (err) {
-        clearTimeout(timer);
-        this.pendingRequests.delete(requestId);
-        reject(err);
-      }
-    });
-  }
-
-  /**
-   * Pick a socket to a target service (round-robin).
-   * @returns {net.Socket|null}
-   */
-  _pickSocket(target) {
-    const keys = this.serviceConnections.get(target);
-    if (!keys || keys.length === 0) return null;
-
-    const startIdx = (this.rrIndex.get(target) ?? 0) % keys.length;
-    this.rrIndex.set(target, (startIdx + 1) % 1_000_000_000);
-
-    // Try from startIdx, skip dead sockets
-    const dead = [];
-    let found = null;
-    for (let attempt = 0; attempt < keys.length; attempt++) {
-      const idx = (startIdx + attempt) % keys.length;
-      const socket = this.outbound.get(keys[idx]);
-      if (socket && !socket.destroyed) {
-        found = socket;
-        break;
-      }
-      dead.push(idx);
-    }
-    // Remove dead entries after the loop (reverse order to preserve indices)
-    for (let i = dead.length - 1; i >= 0; i--) {
-      keys.splice(dead[i], 1);
-    }
-    return found;
-  }
-
-  /**
-   * P19: O(1) socket → key lookup via reverse Map (replaces linear scan).
-   * @param {net.Socket} socket
-   * @returns {string}
-   */
-  _socketKey(socket) {
-    return this._socketKeyMap.get(socket) ?? 'unknown';
-  }
-
-  /**
-   * Reject all pending requests that were sent over a specific socket.
-   * @param {string} deadKey - the socket key that died
-   */
-  _rejectPendingForSocket(deadKey) {
-    for (const [id, entry] of this.pendingRequests) {
-      if (entry.socketKey === deadKey) {
-        clearTimeout(entry.timer);
-        this.pendingRequests.delete(id);
-        entry.reject(new Error('Connection lost to peer'));
-      }
-    }
-  }
-
-  hasDirectConnection(target) {
-    const keys = this.serviceConnections.get(target);
-    return keys && keys.length > 0;
-  }
-
-  topology() {
-    const result = {};
-    for (const [service, keys] of this.serviceConnections) {
-      result[service] = {
-        connections: keys.length,
-        keys,
-      };
-    }
-    return result;
-  }
-
-  destroy() {
-    // Clear reconnect timers to prevent firing after shutdown
-    for (const timer of this._reconnectTimers.values()) clearTimeout(timer);
-    this._reconnectTimers.clear();
-
-    // Clear all pending request timers and reject pending requests
-    for (const [id, entry] of this.pendingRequests) {
-      if (entry.timer) clearTimeout(entry.timer);
-      entry.reject(new Error('Channel destroyed'));
-    }
-    this.pendingRequests.clear();
-
-    for (const [, socket] of this.outbound) {
-      try {
-        socket.destroy();
-      } catch {}
-    }
-    for (const [, socket] of this.inbound) {
-      try {
-        socket.destroy();
-      } catch {}
-    }
-
-    const cleanup = () => {
-      this.outbound.clear();
-      this.inbound.clear();
-      this.serviceConnections.clear();
-      this._socketKeyMap.clear();
-    };
-
-    if (this._server) {
-      return Promise.race([
-        new Promise((resolve) => {
-          this._server.close(() => {
-            cleanup();
-            resolve();
-          });
-        }),
-        new Promise((resolve) => {
-          setTimeout(() => {
-            try { this._server.close(); } catch {}
-            cleanup();
-            resolve();
-          }, 5000).unref();
-        }),
-      ]);
-    }
-
-    cleanup();
-    return Promise.resolve();
-  }
-}