threadforge 0.1.1 → 0.2.1

package/dist/core/WorkerChannelManager.js

@@ -0,0 +1,956 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { IPC_PROTOCOL_VERSION } from "./ipc-errors.js";
+/**
+ * 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;
+/** IPC-H2: Maximum queued messages per service during reconnection */
+const MAX_RECONNECT_QUEUE = 1000;
+/**
+ * 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.
+ */
+function createFrameParser(onFrame, serviceName, socket) {
+    const chunks = [];
+    let totalLength = 0;
+    let buffer = Buffer.alloc(0);
+    let parseErrorCount = 0;
+    let skipRemaining = 0; // bytes left to discard from an oversized message
+    return (chunk) => {
+        // If we're discarding bytes from an oversized message, consume from this chunk first
+        if (skipRemaining > 0) {
+            if (chunk.length <= skipRemaining) {
+                skipRemaining -= chunk.length;
+                return; // entire chunk consumed by skip
+            }
+            chunk = chunk.subarray(skipRemaining);
+            skipRemaining = 0;
+        }
+        // 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})`);
+                // IPC-M1: Drain any complete valid frames from the existing buffer before discarding
+                if (chunks.length > 0) {
+                    buffer = Buffer.concat([buffer, ...chunks]);
+                    chunks.length = 0;
+                    totalLength = 0;
+                }
+                while (buffer.length >= 4) {
+                    const frameLen = buffer.readUInt32BE(0);
+                    if (frameLen > MAX_UDS_MESSAGE) {
+                        // This frame is oversized — discard the rest of the buffer
+                        break;
+                    }
+                    if (buffer.length < 4 + frameLen) {
+                        // Incomplete frame — can't recover it without the new chunk
+                        break;
+                    }
+                    const frameBuf = buffer.subarray(4, 4 + frameLen);
+                    buffer = buffer.subarray(4 + frameLen);
+                    try {
+                        const msg = JSON.parse(frameBuf.toString(), (key, value) => {
+                            if (key === "__proto__" || key === "constructor" || key === "prototype")
+                                return undefined;
+                            return value;
+                        });
+                        onFrame(msg);
+                    }
+                    catch {
+                        // skip unparseable frame
+                    }
+                }
+                // Discard whatever remains (partial or oversized)
+                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 full frame (error ${parseErrorCount}/${MAX_PARSE_ERRORS})`);
+                // Skip the entire frame: 4-byte length prefix + msgLen body
+                const totalFrameSize = 4 + msgLen;
+                if (buffer.length >= totalFrameSize) {
+                    // Full oversized frame is in buffer — skip it entirely
+                    buffer = buffer.subarray(totalFrameSize);
+                }
+                else {
+                    // Frame body hasn't fully arrived — track remaining bytes to discard
+                    skipRemaining = totalFrameSize - buffer.length;
+                    buffer = Buffer.alloc(0);
+                }
+                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) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[${serviceName}] Failed to parse UDS message:`, message);
+            }
+        }
+    };
+}
+/**
+ * IPC-C2: Safe JSON serializer that handles circular references, BigInt, and Buffer.
+ */
+function safeJsonStringify(obj) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (_key, value) => {
+        // Handle BigInt
+        if (typeof value === "bigint") {
+            return { __bigint: value.toString() };
+        }
+        // Handle Buffer
+        if (Buffer.isBuffer(value)) {
+            return { __buffer: value.toString("base64") };
+        }
+        // Detect circular references
+        if (value !== null && typeof value === "object") {
+            if (seen.has(value)) {
+                throw new TypeError("Cannot serialize IPC message: circular reference detected");
+            }
+            seen.add(value);
+        }
+        return value;
+    });
+}
+export class WorkerChannelManager {
+    serviceName;
+    workerId;
+    _dependencies;
+    _onChannelDead;
+    _server;
+    _socketPath;
+    outbound;
+    inbound;
+    serviceConnections;
+    rrIndex;
+    pendingRequests;
+    requestCounter;
+    _workerId;
+    onMessage;
+    onRequest;
+    _supervisorSend;
+    _registry;
+    _reconnectAttempts;
+    _reconnectTimers;
+    _socketKeyMap;
+    backpressureEvents;
+    _reconnectQueue;
+    constructor(serviceName, workerId, options = {}) {
+        this.serviceName = serviceName;
+        this.workerId = workerId;
+        this._dependencies = options.channels ? new Set(options.channels) : null;
+        this._onChannelDead = options.onChannelDead ?? null;
+        this._server = null;
+        this._socketPath = null;
+        this.outbound = new Map();
+        this.inbound = new Map();
+        this.serviceConnections = new Map();
+        this.rrIndex = new Map();
+        this.pendingRequests = new Map();
+        this.requestCounter = 0;
+        /** Worker ID for unique request IDs; falls back to process.pid */
+        this._workerId = workerId ?? process.pid;
+        this.onMessage = null;
+        this.onRequest = null;
+        this._supervisorSend = null;
+        this._registry = {};
+        this._reconnectAttempts = new Map();
+        this._reconnectTimers = new Map();
+        /** P19: Reverse map from socket → key for O(1) lookup */
+        this._socketKeyMap = new Map();
+        this.backpressureEvents = 0;
+        /** IPC-M5: Bounded queue for messages during reconnection */
+        this._reconnectQueue = new Map();
+    }
+    /**
+     * 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) {
+                    // DX-14: Only log handshake timeouts when this service has configured connections.
+                    // Single-service setups with no `connects` targets will never receive inbound
+                    // handshakes, so the timeout is meaningless noise.
+                    if (this._dependencies === null || this._dependencies.size > 0) {
+                        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 {
+                    // ignore
+                }
+                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) {
+                    // DX-14: Suppress noisy timeout warnings for services with no connections configured
+                    if (this._dependencies === null || this._dependencies.size > 0) {
+                        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
+            // IPC-M3: Include timestamp in handshake to prevent replay attacks
+            const handshakeTs = Date.now();
+            const handshake = {
+                type: "forge:handshake",
+                from: this.serviceName,
+                fromWorkerId: this.workerId,
+                ts: handshakeTs,
+                ipcVersion: IPC_PROTOCOL_VERSION,
+            };
+            const clusterSecret = process.env.FORGE_CLUSTER_SECRET;
+            if (clusterSecret) {
+                handshake.hmac = createHmac("sha256", clusterSecret)
+                    .update(`${this.serviceName}:${this.workerId}:${handshakeTs}`)
+                    .digest("hex");
+            }
+            this._sendFrame(socket, handshake);
+            // IPC-M5: Drain queued messages after reconnect
+            const [svcNameForQueue] = key.split(":");
+            const queued = this._reconnectQueue.get(svcNameForQueue);
+            if (queued && queued.length > 0) {
+                this._reconnectQueue.delete(svcNameForQueue);
+                for (const qMsg of queued) {
+                    try {
+                        this._sendFrame(socket, qMsg);
+                    }
+                    catch {
+                        // Best-effort: drop remaining queued messages on backpressure
+                        break;
+                    }
+                }
+            }
+        });
+        // 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 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
+        // H2: Error code allows HTTP layer to return 503 with Retry-After
+        if (socket.writableLength > MAX_WRITE_BUFFER) {
+            const key = this._socketKey(socket);
+            const err = new Error(`IPC write buffer full for ${key} — receiver too slow`);
+            err.code = "ERR_BACKPRESSURE";
+            throw err;
+        }
+        // P6: Buffer.from gives us the buffer directly — byteLength = buf.length, no re-scan
+        // IPC-C2: Use safe serializer to handle circular refs, BigInt, Buffer
+        const json = safeJsonStringify(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.
+     */
+    _sendRawFrame(socket, frameBuffer) {
+        // H2: Error code allows HTTP layer to return 503 with Retry-After
+        if (socket.writableLength > MAX_WRITE_BUFFER) {
+            const key = this._socketKey(socket);
+            const err = new Error(`IPC write buffer full for ${key} — receiver too slow`);
+            err.code = "ERR_BACKPRESSURE";
+            throw err;
+        }
+        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) {
+        // IPC-C2: Use safe serializer to handle circular refs, BigInt, Buffer
+        const json = safeJsonStringify(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;
+                }
+                // IPC version check: fail fast on protocol mismatch
+                const peerVersion = msg.ipcVersion;
+                if (peerVersion !== undefined && peerVersion !== IPC_PROTOCOL_VERSION) {
+                    console.error(`[${this.serviceName}] IPC protocol version mismatch from ${msg.from}:${msg.fromWorkerId}: ` +
+                        `peer=${peerVersion}, local=${IPC_PROTOCOL_VERSION}. ` +
+                        `This usually means mismatched ThreadForge versions. Destroying connection.`);
+                    socket.destroy();
+                    break;
+                }
+                // S-IPC-1: Verify HMAC if cluster secret is configured
+                const clusterSecret = process.env.FORGE_CLUSTER_SECRET;
+                if (clusterSecret) {
+                    // IPC-M3: Reject handshakes with stale timestamps (30s window)
+                    const HANDSHAKE_MAX_AGE_MS = 30_000;
+                    const ts = typeof msg.ts === "number" ? msg.ts : 0;
+                    if (Math.abs(Date.now() - ts) > HANDSHAKE_MAX_AGE_MS) {
+                        console.error(`[${this.serviceName}] Handshake rejected: timestamp too old or missing for ${msg.from}:${msg.fromWorkerId}`);
+                        socket.destroy();
+                        break;
+                    }
+                    const expected = createHmac("sha256", clusterSecret).update(`${msg.from}:${msg.fromWorkerId}:${ts}`).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) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    console.warn(`[${this.serviceName}] Failed to send handshake ack: ${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) {
+                            const message = sendErr instanceof Error ? sendErr.message : String(sendErr);
+                            console.error(`[${this.serviceName}] Failed to send response: ${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) {
+                            const message = sendErr instanceof Error ? sendErr.message : String(sendErr);
+                            console.error(`[${this.serviceName}] Failed to send error response: ${message}`);
+                        }
+                    });
+                }
+                break;
+            }
+            case "forge:response": {
+                const pending = this.pendingRequests.get(msg.requestId);
+                if (pending && !pending.settled) {
+                    pending.settled = true;
+                    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 ("code" in errObj && errObj.code)
+                            err.code = errObj.code;
+                        if ("statusCode" in errObj && 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 {
+            // IPC-H2: Queue messages during reconnection instead of throwing immediately
+            const isReconnecting = this._reconnectTimers.has(target) ||
+                [...this._reconnectTimers.keys()].some((k) => k.startsWith(`${target}:`));
+            if (isReconnecting) {
+                const queue = this._reconnectQueue.get(target) ?? [];
+                if (queue.length >= MAX_RECONNECT_QUEUE) {
+                    // IPC-H2: Drop oldest message to make room, preserving ordering for newer messages
+                    queue.shift();
+                    console.warn(`[${this.serviceName}] Reconnect queue full for "${target}" (max ${MAX_RECONNECT_QUEUE}) — dropping oldest message`);
+                }
+                queue.push({ type: "forge:message", from: this.serviceName, payload });
+                this._reconnectQueue.set(target, queue);
+                return;
+            }
+            // IPC-C1: Supervisor has no handler for forge:send — fail loudly instead of silently dropping
+            throw new Error(`[${this.serviceName}] No UDS connection to "${target}" — cannot send message (no supervisor fallback)`);
+        }
+    }
+    /**
+     * 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,
+            });
+            // IPC-M4: Copy keys array to avoid mutation during iteration
+            // (socket error handlers may splice from the original array)
+            for (const key of [...keys]) {
+                const socket = this.outbound.get(key);
+                if (socket) {
+                    try {
+                        this._sendRawFrame(socket, frame);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.warn(`[${this.serviceName}] Broadcast to ${key} failed: ${message}`);
+                    }
+                }
+            }
+        }
+        else {
+            // IPC-C1: Supervisor has no handler for forge:broadcast — warn instead of silently dropping
+            console.warn(`[${this.serviceName}] No UDS connections to "${target}" — broadcast dropped (no supervisor fallback)`);
+        }
+    }
+    /**
+     * 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(() => {
+                const entry = this.pendingRequests.get(requestId);
+                if (entry?.settled)
+                    return;
+                if (entry)
+                    entry.settled = true;
+                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, settled: false });
+            try {
+                if (socket) {
+                    this._sendFrame(socket, {
+                        type: "forge:request",
+                        requestId,
+                        from: this.serviceName,
+                        payload,
+                    });
+                }
+                else {
+                    // IPC-C1: Supervisor has no handler for forge:request — fail loudly instead of silently dropping
+                    throw new Error(`[${this.serviceName}] No UDS connection to "${target}" — cannot send request (no supervisor fallback)`);
+                }
+            }
+            catch (err) {
+                const entry = this.pendingRequests.get(requestId);
+                if (entry?.settled)
+                    return;
+                if (entry)
+                    entry.settled = true;
+                clearTimeout(timer);
+                this.pendingRequests.delete(requestId);
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Pick a socket to a target service (round-robin).
+     */
+    _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).
+     */
+    _socketKey(socket) {
+        return this._socketKeyMap.get(socket) ?? "unknown";
+    }
+    /**
+     * Reject all pending requests that were sent over a specific socket.
+     */
+    _rejectPendingForSocket(deadKey) {
+        for (const [id, entry] of this.pendingRequests) {
+            if (entry.socketKey === deadKey) {
+                if (entry.settled)
+                    continue;
+                entry.settled = true;
+                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 !== undefined && 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();
+        // IPC-M5: Drop queued messages
+        this._reconnectQueue.clear();
+        // Clear all pending request timers and reject pending requests
+        for (const [, entry] of this.pendingRequests) {
+            if (entry.settled)
+                continue;
+            entry.settled = true;
+            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 {
+                // ignore
+            }
+        }
+        for (const [, socket] of this.inbound) {
+            try {
+                socket.destroy();
+            }
+            catch {
+                // ignore
+            }
+        }
+        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 {
+                            // ignore
+                        }
+                        cleanup();
+                        resolve();
+                    }, 5000).unref();
+                }),
+            ]);
+        }
+        cleanup();
+        return Promise.resolve();
+    }
+}
+//# sourceMappingURL=WorkerChannelManager.js.map