threadforge 0.1.0

package/src/core/WorkerChannelManager.js

@@ -0,0 +1,879 @@
+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();
+  }
+}