socketduct 0.1.15

package/src/client/multiplexed-transport-set.js

@@ -0,0 +1,917 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-returns, jsdoc/require-returns-description */
+import {createHash} from "node:crypto"
+import {EventEmitter} from "node:events"
+import {tmpdir} from "node:os"
+import {join, resolve} from "node:path"
+import {connect as tlsConnect} from "node:tls"
+
+import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
+import {ReverseGatewayConnection} from "../reverse/client.js"
+import {DeferredVirtualSocket} from "./deferred-virtual-socket.js"
+import {MultiplexedSocketductConnection} from "./multiplexed-connection.js"
+
+const DEFAULT_TOTAL_BUFFER_BYTES = 32 * 1024 * 1024
+const DEFAULT_TOTAL_SPOOL_BYTES = 32 * 1024 * 1024
+const DEFAULT_TOTAL_QUEUED_BYTES = 33 * 1024 * 1024
+const DEFAULT_MAX_PENDING_OPENS = 1_024
+const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
+const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
+
+/**
+ * @typedef {object} GatewayEndpoint
+ * @property {{host: string, port: number, token: string}} [relay] - Gateway-pinned ordinary relay endpoint.
+ * @property {{host: string, port: number, token: string}} [reverseHub] - Shared reverse hub endpoint; gatewayId selects its registered member.
+ * @property {{caFile?: string, certFile?: string, keyFile?: string, servername?: string, rejectUnauthorized?: boolean}} [tls] - Outer TLS settings.
+ * @property {(options: {host: string, port: number, tls?: Record<string, unknown>}) => import('node:net').Socket} [createPhysicalSocket] - Gateway-pinned physical socket factory.
+ * @typedef {object} GatewayConfiguration
+ * @property {string} gatewayId - Stable, privacy-safe gateway identity.
+ * @property {GatewayEndpoint} endpoint - Explicit gateway-pinned endpoint/factory.
+ * @typedef {object} TransportSetOptions
+ * @property {string} connectionId - Stable process/base connection identity.
+ * @property {string} [spoolDirectory] - Base directory for derived gateway spool namespaces.
+ * @property {GatewayConfiguration[]} gateways - Explicit configured gateways.
+ * @property {number} [minimumReadyMembers] - Required ready members for start(), default 1.
+ * @property {number} [maxTotalBufferBytes] - Set-wide retained data limit.
+ * @property {number} [maxTotalSpoolBytes] - Set-wide durable spool data limit.
+ * @property {number} [maxTotalQueuedBytes] - Set-wide retained data plus control queue limit.
+ * @property {number} [maxPendingOpens] - Maximum sockets awaiting an eligible ready member, default 1024.
+ * @property {Record<string, unknown>} [memberOptions] - Shared single-member v3 options other than identity and endpoint.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured logger shared by the set and its members.
+ * @typedef {object} MemberConnectionStatus
+ * @property {string} physicalState - Member lifecycle.
+ * @property {number} connectionGeneration - Current authenticated generation.
+ * @property {number} physicalConnects - Authenticated physical generations.
+ * @property {number} reconnectAttempts - Physical reconnect attempts.
+ * @property {number} reconnectSuccesses - Successful resumptions.
+ * @property {number} virtualStreams - Current virtual streams.
+ * @property {number} queuedBytes - Current retained and control bytes.
+ * @property {number} spoolBytes - Current durable spool bytes.
+ * @property {number} spoolCleanupFailures - Durable cleanup failures retained for visibility.
+ * @typedef {object} TransportMemberConnection
+ * @property {() => Promise<void>} connect - Warm the member.
+ * @property {(options: Record<string, unknown>, callback?: (error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) => import('./virtual-socket.js').VirtualSocket} createConnection - Open a virtual stream.
+ * @property {(options: Record<string, unknown>, callback?: (error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) => import('./virtual-socket.js').VirtualSocket} registerRecoveredConnection - Cold-register durable recovery.
+ * @property {() => MemberConnectionStatus} status - Privacy-safe status.
+ * @property {() => Promise<void>} close - Close the member.
+ * @property {() => Promise<void>} detach - Preserve durable streams for process-replacement recovery.
+ * @property {(eventName: string, listener: (...args: unknown[]) => void) => unknown} on - Subscribe to lifecycle changes.
+ * @property {() => unknown} [ref] - Reference resources.
+ * @property {() => unknown} [unref] - Unreference resources.
+ * @typedef {object} TransportSetDependencies
+ * @property {(options: import('./multiplexed-connection.js').MultiplexedConnectionOptions | import('../reverse/client.js').ReverseGatewayConnectionOptions, gatewayId: string) => TransportMemberConnection} [createMember] - Narrow test dependency.
+ * @typedef {object} TransportMember
+ * @property {string} gatewayId - Stable gateway ID.
+ * @property {TransportMemberConnection} connection - Single-lane owner.
+ * @property {number} assignments - Virtual sockets assigned for life.
+ * @property {Error | undefined} startupError - Terminal startup error.
+ * @property {Error | undefined} terminalError - Terminal member error after readiness.
+ * @property {number | undefined} lastReadyGeneration - Last generation that reached readiness.
+ * @typedef {object} PendingOpen
+ * @property {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Validated caller options.
+ * @property {DeferredVirtualSocket} socket - Immediate app-facing socket.
+ * @typedef {import('./virtual-socket.js').VirtualSocket & {readonly gatewayId: string | undefined}} GatewayVirtualSocket
+ * @typedef {import('node:tls').TLSSocket & {readonly gatewayId: string | undefined}} GatewayTlsSocket
+ */
+
+/** No configured gateway is currently safe for a new virtual stream. */
+export class SocketductTransportSetNotReadyError extends Error {
+  /** @param {string} [message] - Privacy-safe detail. */
+  constructor(message = "No Socketduct gateway member is currently ready") {
+    super(message)
+    this.name = "SocketductTransportSetNotReadyError"
+    this.code = "SOCKETDUCT_TRANSPORT_SET_NOT_READY"
+  }
+}
+
+/** Set-level resource exhaustion before bytes enter a member. */
+export class SocketductTransportSetLimitError extends Error {
+  /**
+   * @param {string} message - Privacy-safe detail.
+   * @param {string} code - Stable code.
+   */
+  constructor(message, code) {
+    super(message)
+    this.name = "SocketductTransportSetLimitError"
+    this.code = code
+  }
+}
+
+/** Every configured member became terminal after the set reached readiness. */
+export class SocketductTransportSetTerminalError extends AggregateError {
+  /** @param {Error[]} errors - Member errors in configured gateway order. */
+  constructor(errors) {
+    super(errors, "All Socketduct transport-set members closed")
+    this.name = "SocketductTransportSetTerminalError"
+    this.code = "SOCKETDUCT_TRANSPORT_SET_TERMINAL"
+  }
+}
+
+/** Shared retained-byte reservations across every configured member. */
+class AggregateTransportBudget {
+  #memoryBytes = 0
+  #spoolBytes = 0
+  #controlBytes = 0
+
+  /** @param {{maxDataBytes: number, maxSpoolBytes: number, maxQueuedBytes: number}} limits - Process limits. */
+  constructor(limits) {
+    this.maxDataBytes = limits.maxDataBytes
+    this.maxSpoolBytes = limits.maxSpoolBytes
+    this.maxQueuedBytes = limits.maxQueuedBytes
+  }
+
+  /** @param {number} bytes - Retained and durably spooled data bytes. */
+  reserveData(bytes) {
+    validateReservation(bytes)
+    if (this.#memoryBytes + bytes > this.maxDataBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set data buffer limit exceeded", "SOCKETDUCT_SET_BUFFER_LIMIT")
+    if (this.#spoolBytes + bytes > this.maxSpoolBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set spool limit exceeded", "SOCKETDUCT_SET_SPOOL_LIMIT")
+    if (this.#memoryBytes + this.#controlBytes + bytes > this.maxQueuedBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set queued-byte limit exceeded", "SOCKETDUCT_SET_QUEUE_LIMIT")
+    this.#memoryBytes += bytes
+    this.#spoolBytes += bytes
+  }
+
+  /** @param {number} bytes - Retained non-durable reverse-stream bytes. */
+  reserveMemory(bytes) {
+    validateReservation(bytes)
+    if (this.#memoryBytes + bytes > this.maxDataBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set data buffer limit exceeded", "SOCKETDUCT_SET_BUFFER_LIMIT")
+    if (this.#memoryBytes + this.#controlBytes + bytes > this.maxQueuedBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set queued-byte limit exceeded", "SOCKETDUCT_SET_QUEUE_LIMIT")
+    this.#memoryBytes += bytes
+  }
+
+  /** @param {number} bytes - Released in-memory data bytes. */
+  releaseMemory(bytes) {
+    validateReservation(bytes)
+    if (bytes > this.#memoryBytes) throw new Error("Socketduct transport-set memory budget release underflow")
+    this.#memoryBytes -= bytes
+  }
+
+  /** @param {number} bytes - Bytes successfully removed from durable spool storage. */
+  releaseSpool(bytes) {
+    validateReservation(bytes)
+    if (bytes > this.#spoolBytes) throw new Error("Socketduct transport-set spool budget release underflow")
+    this.#spoolBytes -= bytes
+  }
+
+  /** @param {number} bytes - Queued control bytes. */
+  reserveControl(bytes) {
+    validateReservation(bytes)
+    if (this.#memoryBytes + this.#controlBytes + bytes > this.maxQueuedBytes) throw new SocketductTransportSetLimitError("Socketduct transport-set queued-byte limit exceeded", "SOCKETDUCT_SET_QUEUE_LIMIT")
+    this.#controlBytes += bytes
+  }
+
+  /** @param {number} bytes - Released control bytes. */
+  releaseControl(bytes) {
+    validateReservation(bytes)
+    if (bytes > this.#controlBytes) throw new Error("Socketduct transport-set control budget release underflow")
+    this.#controlBytes -= bytes
+  }
+
+  /** @returns {{dataBytes: number, spoolBytes: number, queuedBytes: number, maxDataBytes: number, maxSpoolBytes: number, maxQueuedBytes: number}} */
+  status() {
+    return {
+      dataBytes: this.#memoryBytes,
+      spoolBytes: this.#spoolBytes,
+      queuedBytes: this.#memoryBytes + this.#controlBytes,
+      maxDataBytes: this.maxDataBytes,
+      maxSpoolBytes: this.maxSpoolBytes,
+      maxQueuedBytes: this.maxQueuedBytes
+    }
+  }
+}
+
+/** One process-wide set of explicit gateway-pinned v3 member connections. */
+export class MultiplexedSocketductTransportSet extends EventEmitter {
+  /** @type {TransportMember[]} */
+  #members
+
+  /** @type {AggregateTransportBudget} */
+  #budget
+
+  /** @type {number} */
+  #minimumReadyMembers
+
+  /** @type {number} */
+  #maxPendingOpens
+
+  /** @type {PendingOpen[]} */
+  #pendingOpens = []
+
+  /** @type {number} */
+  #cursor = 0
+
+  /** @type {number} */
+  #virtualOpens = 0
+
+  /** @type {boolean} */
+  #started = false
+
+  /** @type {boolean} */
+  #startupResolved = false
+
+  /** @type {Error | undefined} */
+  #startupError
+
+  /** @type {boolean} */
+  #closed = false
+
+  /** @type {Promise<void> | undefined} */
+  #startPromise
+
+  /** @type {(() => void) | undefined} */
+  #resolveStart
+
+  /** @type {((error: Error) => void) | undefined} */
+  #rejectStart
+
+  /** @type {Promise<void> | undefined} */
+  #closePromise
+
+  /** @type {import('../logging/structured-logger.js').DiagnosticLogger | undefined} */
+  #logger
+
+  /**
+   * @param {TransportSetOptions} options - Explicit set and gateway policy.
+   * @param {TransportSetDependencies} [dependencies] - Narrow test dependencies.
+   */
+  constructor(options, dependencies = {}) {
+    super()
+    const validated = validateTransportSetOptions(options)
+    this.#minimumReadyMembers = validated.minimumReadyMembers
+    this.#maxPendingOpens = validated.maxPendingOpens
+    this.#budget = new AggregateTransportBudget(validated.limits)
+    this.#logger = options.logger
+    const createMember = dependencies.createMember ?? ((memberOptions) => "gatewayId" in memberOptions
+      ? new ReverseGatewayConnection(memberOptions)
+      : new MultiplexedSocketductConnection(memberOptions))
+    this.#members = validated.gateways.map(({gatewayId, endpoint}) => {
+      const identity = deriveGatewayIdentity(options.connectionId, gatewayId)
+      const memberOptions = endpoint.reverseHub === undefined
+        ? /** @type {import('./multiplexed-connection.js').MultiplexedConnectionOptions} */ ({
+          ...validated.memberOptions,
+          relay: endpoint.relay,
+          ...(endpoint.tls === undefined ? {} : {tls: endpoint.tls}),
+          ...(endpoint.createPhysicalSocket === undefined ? {} : {createPhysicalSocket: endpoint.createPhysicalSocket}),
+          connectionId: identity.connectionId,
+          spoolDirectory: join(validated.spoolDirectory, identity.spoolName),
+          continuousReconnect: true,
+          aggregateBudget: this.#budget,
+          ...(this.#logger === undefined ? {} : {logger: this.#logger})
+        })
+        : /** @type {import('../reverse/client.js').ReverseGatewayConnectionOptions} */ (/** @type {unknown} */ ({
+          ...validated.memberOptions,
+          gatewayId,
+          hub: endpoint.reverseHub,
+          tls: endpoint.tls,
+          ...(endpoint.createPhysicalSocket === undefined ? {} : {createPhysicalSocket: endpoint.createPhysicalSocket}),
+          connectionId: identity.connectionId,
+          continuousReconnect: true,
+          aggregateBudget: this.#budget,
+          ...(this.#logger === undefined ? {} : {logger: this.#logger})
+        }))
+      const connection = /** @type {TransportMemberConnection} */ (createMember(memberOptions, gatewayId))
+      validateMember(connection)
+      /** @type {TransportMember} */
+      const member = {gatewayId, connection, assignments: 0, startupError: undefined, terminalError: undefined, lastReadyGeneration: undefined}
+      connection.on("stateChange", (state, error) => this.#memberStateChanged(member, state, error))
+      return member
+    })
+    this.createConnection = this.createConnection.bind(this)
+    this.recoverConnection = this.recoverConnection.bind(this)
+    this.createTlsConnection = this.createTlsConnection.bind(this)
+  }
+
+  /** Starts every configured member concurrently and waits for minimum readiness. @returns {Promise<void>} */
+  start() {
+    if (this.#startPromise !== undefined) return this.#startPromise
+    if (this.#closed) return Promise.reject(closedError())
+    this.#started = true
+    logDiagnostic(this.#logger, "transport_set.started", {
+      configuredMembers: this.#members.length,
+      minimumReadyMembers: this.#minimumReadyMembers
+    })
+    this.#startPromise = new Promise((resolve, reject) => {
+      this.#resolveStart = resolve
+      this.#rejectStart = reject
+    })
+    for (const member of this.#members) {
+      try {
+        Promise.resolve(member.connection.connect()).catch((error) => {
+          member.startupError = asError(error)
+          this.#memberStateChanged()
+        })
+      } catch (error) {
+        member.startupError = asError(error)
+      }
+    }
+    this.#evaluateStartup()
+    return this.#startPromise
+  }
+
+  /**
+   * Assigns one new virtual socket to the next ready member.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Target/socket options.
+   * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
+   * @returns {GatewayVirtualSocket} Sticky member-owned virtual socket with stable gateway metadata.
+   */
+  createConnection(options, callback) {
+    validateOrdinaryOpenOptions(options)
+    if (this.#closed) throw closedError()
+    const socketOptions = normalizeVirtualSocketOptions(options)
+    if (this.#startupError !== undefined) return this.#failedSocket(socketOptions, this.#startupError, callback)
+    const selection = this.#pendingOpens.length === 0 && this.#startupResolved ? this.#selectReadyMember() : undefined
+    if (selection === undefined) return this.#deferConnection(options, socketOptions, callback)
+    try {
+      /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
+      const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeGateway(socket, selection.member.gatewayId))
+      const socket = exposeGateway(/** @type {import('./virtual-socket.js').VirtualSocket} */ (selection.member.connection.createConnection(options, memberCallback)), selection.member.gatewayId)
+      selection.member.assignments += 1
+      this.#virtualOpens += 1
+      return socket
+    } catch (error) {
+      this.#cursor = selection.previousCursor
+      throw error
+    }
+  }
+
+  /**
+   * Returns an app-facing socket while the set owns readiness and assignment.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Validated member open options.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Normal socket metadata.
+   * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
+   * @returns {GatewayVirtualSocket} Deferred socket.
+   */
+  #deferConnection(options, socketOptions, callback) {
+    if (this.#pendingOpens.length >= this.#maxPendingOpens) {
+      throw new SocketductTransportSetLimitError("Socketduct transport-set pending-open limit exceeded", "SOCKETDUCT_SET_PENDING_OPEN_LIMIT")
+    }
+    /** @type {PendingOpen | undefined} */
+    let pending
+    const socket = new DeferredVirtualSocket(socketOptions, {
+      budget: this.#budget,
+      onCancel: () => {
+        if (pending === undefined) return
+        const index = this.#pendingOpens.indexOf(pending)
+        if (index !== -1) this.#pendingOpens.splice(index, 1)
+      },
+      ref: () => this.ref(),
+      unref: () => this.unref()
+    })
+    if (callback !== undefined) installConnectCallback(/** @type {GatewayVirtualSocket} */ (socket), callback)
+    pending = {
+      options: {
+        ...options,
+        ...(options.target === undefined || options.target === null ? {} : {target: {...options.target}})
+      },
+      socket
+    }
+    this.#pendingOpens.push(pending)
+    if (!this.#started) {
+      this.start().catch((error) => this.#recordStartupFailure(asError(error)))
+    }
+    this.#drainPendingOpens()
+    return /** @type {GatewayVirtualSocket} */ (socket)
+  }
+
+  /**
+   * Creates a socket that asynchronously reports the already-terminal startup failure.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Normal socket metadata.
+   * @param {Error} error - Terminal startup failure.
+   * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
+   * @returns {GatewayVirtualSocket} Failed socket facade.
+   */
+  #failedSocket(socketOptions, error, callback) {
+    const socket = new DeferredVirtualSocket(socketOptions, {
+      budget: this.#budget,
+      onCancel: () => {},
+      ref: () => this.ref(),
+      unref: () => this.unref()
+    })
+    if (callback !== undefined) installConnectCallback(/** @type {GatewayVirtualSocket} */ (socket), callback)
+    queueMicrotask(() => socket._receiveError(error))
+    return /** @type {GatewayVirtualSocket} */ (socket)
+  }
+
+  /**
+   * Registers a durable stream on its original gateway before any member starts.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & {gatewayId: string}} options - Original gateway and recovery identity.
+   * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
+   * @returns {GatewayVirtualSocket} Original member-owned virtual socket with stable gateway metadata.
+   */
+  recoverConnection(options, callback) {
+    if (this.#closed) throw closedError()
+    if (this.#started) throw new Error("Recovered streams must be registered before start()")
+    if (typeof options !== "object" || options === null || typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId)) throw new TypeError("recoverConnection requires a valid configured gatewayId")
+    if (Object.hasOwn(options, "recover")) throw new TypeError("recoverConnection owns the recover option")
+    const member = this.#members.find((candidate) => candidate.gatewayId === options.gatewayId)
+    if (member === undefined) throw new Error(`Unknown gatewayId: ${options.gatewayId}`)
+    const virtualOptions = {...options}
+    delete /** @type {{gatewayId?: string}} */ (virtualOptions).gatewayId
+    /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
+    const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeGateway(socket, member.gatewayId))
+    const socket = exposeGateway(/** @type {import('./virtual-socket.js').VirtualSocket} */ (member.connection.registerRecoveredConnection({...virtualOptions, recover: true}, memberCallback)), member.gatewayId)
+    member.assignments += 1
+    this.#virtualOpens += 1
+    return socket
+  }
+
+  /**
+   * Opens a sticky virtual socket and wraps it with an ordinary target TLS socket.
+   * @param {Record<string, unknown>} options - Virtual target plus tls.connect options.
+   * @param {(error: Error | null, socket: GatewayTlsSocket) => void} [callback] - Optional callback.
+   * @returns {GatewayTlsSocket} Target TLS socket with stable gateway metadata.
+   */
+  createTlsConnection(options, callback) {
+    validateOrdinaryOpenOptions(options)
+    const virtualOptions = pickVirtualOptions(options)
+    const raw = this.createConnection(virtualOptions)
+    const tlsOptions = omitVirtualOptions(options)
+    const secure = tlsConnect({...tlsOptions, socket: raw})
+    const exposed = exposeGatewayGetter(secure, () => raw.gatewayId)
+    if (callback !== undefined) installTlsCallback(exposed, callback)
+    return exposed
+  }
+
+  /** @returns {this} References every member. */
+  ref() {
+    for (const member of this.#members) member.connection.ref?.()
+    return this
+  }
+
+  /** @returns {this} Unreferences every member. */
+  unref() {
+    for (const member of this.#members) member.connection.unref?.()
+    return this
+  }
+
+  /** @returns {{state: string, configuredMembers: number, connectingMembers: number, readyMembers: number, degradedMembers: number, closedMembers: number, minimumReadyMembers: number, pendingOpens: number, maxPendingOpens: number, virtualOpens: number, physicalConnects: number, reconnectAttempts: number, budgets: {dataBytes: number, spoolBytes: number, queuedBytes: number, maxDataBytes: number, maxSpoolBytes: number, maxQueuedBytes: number}, members: Array<{gatewayId: string, state: string, assignments: number, physicalConnects: number, reconnectAttempts: number, reconnectSuccesses: number, virtualStreams: number, queuedBytes: number, spoolBytes: number, spoolCleanupFailures: number, terminalErrorCode: string | null}>}} Privacy-safe aggregate and per-gateway status. */
+  status() {
+    const members = this.#members.map((member) => {
+      const status = member.connection.status()
+      return {
+        gatewayId: member.gatewayId,
+        state: status.physicalState,
+        assignments: member.assignments,
+        physicalConnects: status.physicalConnects,
+        reconnectAttempts: status.reconnectAttempts,
+        reconnectSuccesses: status.reconnectSuccesses,
+        virtualStreams: status.virtualStreams,
+        queuedBytes: status.queuedBytes,
+        spoolBytes: status.spoolBytes,
+        spoolCleanupFailures: status.spoolCleanupFailures,
+        terminalErrorCode: publicErrorCode(member.terminalError ?? member.startupError)
+      }
+    })
+    const readyMembers = members.filter((member) => member.state === "ready").length
+    const connectingMembers = members.filter((member) => member.state === "connecting").length
+    const closedMembers = members.filter((member) => member.state === "closed").length
+    const degradedMembers = members.length - readyMembers - connectingMembers - closedMembers
+    let state = "configured"
+    if (this.#closed) state = "closed"
+    else if (this.#startupError !== undefined) state = "failed"
+    else if (this.#started && readyMembers === members.length) state = "ready"
+    else if (this.#started && (this.#startupResolved || readyMembers > 0)) state = "degraded"
+    else if (this.#started) state = "starting"
+    return {
+      state,
+      configuredMembers: members.length,
+      connectingMembers,
+      readyMembers,
+      degradedMembers,
+      closedMembers,
+      minimumReadyMembers: this.#minimumReadyMembers,
+      pendingOpens: this.#pendingOpens.length,
+      maxPendingOpens: this.#maxPendingOpens,
+      virtualOpens: this.#virtualOpens,
+      physicalConnects: members.reduce((sum, member) => sum + member.physicalConnects, 0),
+      reconnectAttempts: members.reduce((sum, member) => sum + member.reconnectAttempts, 0),
+      budgets: this.#budget.status(),
+      members
+    }
+  }
+
+  /** Closes every configured member once and preserves ordered failures. @returns {Promise<void>} */
+  close() {
+    return this.#shutdown("close")
+  }
+
+  /** Preserves member spools for a replacement set and closes every physical member once. @returns {Promise<void>} */
+  detach() {
+    return this.#shutdown("detach")
+  }
+
+  /** @param {"close" | "detach"} method - Member shutdown operation. @returns {Promise<void>} */
+  #shutdown(method) {
+    if (this.#closePromise !== undefined) return this.#closePromise
+    this.#closed = true
+    const error = closedError()
+    this.#rejectStart?.(error)
+    this.#failPendingOpens(error)
+    this.emit("stateChange", this.status())
+    this.#closePromise = Promise.allSettled(this.#members.map((member) => {
+      try {
+        return member.connection[method]()
+      } catch (error) {
+        return Promise.reject(error)
+      }
+    })).then((results) => {
+      const errors = results.flatMap((result) => result.status === "rejected" ? [asError(result.reason)] : [])
+      if (errors.length > 0) throw new AggregateError(errors, `One or more Socketduct gateway members failed to ${method}`)
+    })
+    return this.#closePromise
+  }
+
+  /** @returns {{member: TransportMember, previousCursor: number} | undefined} */
+  #selectReadyMember() {
+    if (this.#closed) throw closedError()
+    const previousCursor = this.#cursor
+    for (let offset = 0; offset < this.#members.length; offset += 1) {
+      const index = (this.#cursor + offset) % this.#members.length
+      const member = /** @type {TransportMember} */ (this.#members[index])
+      if (member.connection.status().physicalState !== "ready") continue
+      this.#cursor = (index + 1) % this.#members.length
+      return {member, previousCursor}
+    }
+    return undefined
+  }
+
+  /**
+   * @param {TransportMember} [member] - Member reporting the state.
+   * @param {unknown} [state] - Reported state.
+   * @param {unknown} [error] - Terminal error.
+   * @returns {void}
+   */
+  #memberStateChanged(member, state, error) {
+    if (member !== undefined && state === "closed" && error instanceof Error) member.terminalError = error
+    if (member !== undefined && typeof state === "string") {
+      const status = member.connection.status()
+      logDiagnostic(this.#logger, "transport_set.member_state", {
+        gatewayId: member.gatewayId,
+        state,
+        generation: status.connectionGeneration,
+        physicalConnects: status.physicalConnects,
+        reconnectAttempts: status.reconnectAttempts,
+        ...(error === undefined ? {} : errorClassification(error))
+      })
+      if (state === "ready" && member.lastReadyGeneration !== undefined && status.connectionGeneration > member.lastReadyGeneration) {
+        logDiagnostic(this.#logger, "transport_set.member_replaced", {
+          gatewayId: member.gatewayId,
+          generation: status.connectionGeneration,
+          physicalConnects: status.physicalConnects
+        })
+      }
+      if (state === "ready") member.lastReadyGeneration = status.connectionGeneration
+    }
+    this.#evaluateStartup()
+    this.#evaluateTerminalMemberLoss()
+    this.#drainPendingOpens()
+    this.emit("stateChange", this.status())
+  }
+
+  /** @returns {void} */
+  #evaluateStartup() {
+    if (this.#closed || this.#startPromise === undefined || this.#startupResolved) return
+    const ready = this.#members.filter((member) => member.connection.status().physicalState === "ready").length
+    if (ready >= this.#minimumReadyMembers) {
+      this.#startupResolved = true
+      logDiagnostic(this.#logger, "transport_set.ready", {
+        configuredMembers: this.#members.length,
+        readyMembers: ready,
+        minimumReadyMembers: this.#minimumReadyMembers
+      })
+      this.#resolveStart?.()
+      this.#resolveStart = undefined
+      this.#rejectStart = undefined
+      this.#drainPendingOpens()
+      return
+    }
+    const available = this.#members.filter((member) => member.connection.status().physicalState !== "closed" || member.startupError === undefined).length
+    if (available < this.#minimumReadyMembers) {
+      const errors = this.#members.flatMap((member) => member.startupError === undefined ? [] : [member.startupError])
+      this.#recordStartupFailure(new AggregateError(errors, "Socketduct transport set cannot satisfy minimumReadyMembers"))
+    }
+  }
+
+  /** Assigns pending sockets FIFO while eligible members are ready. */
+  #drainPendingOpens() {
+    if (!this.#startupResolved || this.#closed || this.#startupError !== undefined) return
+    while (this.#pendingOpens.length > 0) {
+      const selection = this.#selectReadyMember()
+      if (selection === undefined) return
+      const pending = this.#pendingOpens.shift()
+      if (pending === undefined) return
+      if (pending.socket.destroyed) {
+        this.#cursor = selection.previousCursor
+        continue
+      }
+      /** @type {import('./virtual-socket.js').VirtualSocket | undefined} */
+      let memberSocket
+      try {
+        memberSocket = exposeGateway(selection.member.connection.createConnection(pending.options), selection.member.gatewayId)
+        if (!pending.socket.assign(memberSocket, selection.member.gatewayId)) {
+          this.#cursor = selection.previousCursor
+          continue
+        }
+        selection.member.assignments += 1
+        this.#virtualOpens += 1
+      } catch (error) {
+        this.#cursor = selection.previousCursor
+        const failure = asError(error)
+        if (memberSocket !== undefined && !memberSocket.destroyed) memberSocket.destroy(failure)
+        pending.socket._receiveError(failure)
+      }
+    }
+  }
+
+  /**
+   * Records the one terminal initial-start error and fails every waiting socket.
+   * @param {Error} error - Terminal error.
+   */
+  #recordStartupFailure(error) {
+    if (this.#startupResolved || this.#startupError !== undefined || this.#closed) return
+    this.#startupError = error
+    logDiagnostic(this.#logger, "transport_set.terminal_failure", {
+      configuredMembers: this.#members.length,
+      closedMembers: this.#members.filter((member) => member.connection.status().physicalState === "closed").length,
+      ...errorClassification(error, "SOCKETDUCT_TRANSPORT_SET_TERMINAL")
+    })
+    this.#rejectStart?.(error)
+    this.#resolveStart = undefined
+    this.#rejectStart = undefined
+    this.#failPendingOpens(error)
+  }
+
+  /** Fails queued sockets if every authenticated member becomes terminal after startup. */
+  #evaluateTerminalMemberLoss() {
+    if (!this.#startupResolved || this.#closed || this.#startupError !== undefined) return
+    if (!this.#members.every((member) => member.connection.status().physicalState === "closed")) return
+    const errors = this.#members.map((member) => member.terminalError ?? member.startupError ?? memberTerminalError())
+    const error = new SocketductTransportSetTerminalError(errors)
+    this.#startupError = error
+    logDiagnostic(this.#logger, "transport_set.terminal_failure", {
+      configuredMembers: this.#members.length,
+      closedMembers: this.#members.length,
+      ...errorClassification(error, "SOCKETDUCT_TRANSPORT_SET_TERMINAL")
+    })
+    this.#failPendingOpens(error)
+  }
+
+  /** @param {Error} error - Terminal failure delivered through normal socket errors. */
+  #failPendingOpens(error) {
+    const pending = this.#pendingOpens
+    this.#pendingOpens = []
+    for (const open of pending) open.socket._receiveError(error)
+  }
+}
+
+/** @param {TransportSetOptions} options - Set policy. @returns {MultiplexedSocketductTransportSet} */
+export function createMultiplexedSocketductTransportSet(options) {
+  return new MultiplexedSocketductTransportSet(options)
+}
+
+/**
+ * Transport-set lifecycle events must not expose arbitrary member error text.
+ * @param {unknown} error - Member or aggregate failure.
+ * @param {string} [fallback] - Known fallback code.
+ * @returns {{errorCode: string, errorClass: string}} Safe error classification.
+ */
+function errorClassification(error, fallback) {
+  const {errorCode, errorClass} = errorDiagnostics(error, fallback)
+  return {errorCode, errorClass}
+}
+
+/** @param {TransportSetOptions} options - Raw policy. */
+function validateTransportSetOptions(options) {
+  if (typeof options !== "object" || options === null) throw new TypeError("Socketduct transport-set options are required")
+  if (typeof options.connectionId !== "string" || !STABLE_IDENTIFIER.test(options.connectionId)) throw new TypeError("Transport-set connectionId must be 8-128 URL-safe opaque characters")
+  if (!Array.isArray(options.gateways) || options.gateways.length === 0) throw new TypeError("Transport-set gateways must be a non-empty array")
+  const minimumReadyMembers = options.minimumReadyMembers === undefined ? 1 : options.minimumReadyMembers
+  if (!Number.isSafeInteger(minimumReadyMembers) || minimumReadyMembers < 1 || minimumReadyMembers > options.gateways.length) throw new RangeError("minimumReadyMembers must be between 1 and the configured gateway count")
+  const maxPendingOpens = positiveLimit(options.maxPendingOpens, DEFAULT_MAX_PENDING_OPENS, "maxPendingOpens")
+  const limits = {
+    maxDataBytes: positiveLimit(options.maxTotalBufferBytes, DEFAULT_TOTAL_BUFFER_BYTES, "maxTotalBufferBytes"),
+    maxSpoolBytes: positiveLimit(options.maxTotalSpoolBytes, DEFAULT_TOTAL_SPOOL_BYTES, "maxTotalSpoolBytes"),
+    maxQueuedBytes: positiveLimit(options.maxTotalQueuedBytes, DEFAULT_TOTAL_QUEUED_BYTES, "maxTotalQueuedBytes")
+  }
+  const memberOptions = options.memberOptions === undefined ? {} : options.memberOptions
+  if (typeof memberOptions !== "object" || memberOptions === null || Array.isArray(memberOptions)) throw new TypeError("memberOptions must be an object")
+  for (const forbidden of ["relay", "hub", "gatewayId", "tls", "createPhysicalSocket", "connectionId", "spoolDirectory", "continuousReconnect", "aggregateBudget", "logger"]) {
+    if (Object.hasOwn(memberOptions, forbidden)) throw new TypeError(`memberOptions.${forbidden} is owned by the transport set`)
+  }
+  /** @type {GatewayConfiguration[]} */
+  const gateways = []
+  const gatewayIds = new Set()
+  for (const raw of options.gateways) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new TypeError("Each gateway entry must be an object")
+    for (const key of Object.keys(raw)) {
+      if (key !== "gatewayId" && key !== "endpoint") throw new TypeError(`Unknown gateway field ${key}; gateway relay and factory settings belong under endpoint`)
+    }
+    const gateway = /** @type {Partial<GatewayConfiguration>} */ (raw)
+    if (typeof gateway.gatewayId !== "string" || !GATEWAY_ID.test(gateway.gatewayId)) throw new TypeError("gatewayId must be 2-64 URL-safe characters and cannot contain path separators")
+    if (gatewayIds.has(gateway.gatewayId)) throw new TypeError(`Duplicate gatewayId: ${gateway.gatewayId}`)
+    gatewayIds.add(gateway.gatewayId)
+    if (typeof gateway.endpoint !== "object" || gateway.endpoint === null || Array.isArray(gateway.endpoint)) throw new TypeError(`Gateway ${gateway.gatewayId} requires an explicit endpoint`)
+    const endpoint = /** @type {Partial<GatewayEndpoint>} */ (gateway.endpoint)
+    for (const key of Object.keys(endpoint)) {
+      if (key !== "relay" && key !== "reverseHub" && key !== "tls" && key !== "createPhysicalSocket") throw new TypeError(`Unknown endpoint field: ${key}`)
+    }
+    if ((endpoint.relay === undefined) === (endpoint.reverseHub === undefined)) throw new TypeError(`Gateway ${gateway.gatewayId} requires exactly one relay or reverseHub endpoint`)
+    const selectedEndpoint = endpoint.relay ?? endpoint.reverseHub
+    if (typeof selectedEndpoint !== "object" || selectedEndpoint === null || typeof selectedEndpoint.host !== "string" || selectedEndpoint.host.length === 0 || !validPort(selectedEndpoint.port) || typeof selectedEndpoint.token !== "string" || selectedEndpoint.token.length === 0) throw new TypeError(`Gateway ${gateway.gatewayId} endpoint host, port, and token are required`)
+    if (endpoint.tls !== undefined && (typeof endpoint.tls !== "object" || endpoint.tls === null || Array.isArray(endpoint.tls))) throw new TypeError(`Gateway ${gateway.gatewayId} tls must be an object`)
+    if (endpoint.reverseHub !== undefined && endpoint.tls === undefined) throw new TypeError(`Gateway ${gateway.gatewayId} reverseHub requires verified TLS settings`)
+    if (endpoint.createPhysicalSocket !== undefined && typeof endpoint.createPhysicalSocket !== "function") throw new TypeError(`Gateway ${gateway.gatewayId} createPhysicalSocket must be a function`)
+    gateways.push(/** @type {GatewayConfiguration} */ ({gatewayId: gateway.gatewayId, endpoint}))
+  }
+  for (let left = 0; left < gateways.length; left += 1) {
+    for (let right = left + 1; right < gateways.length; right += 1) {
+      const first = /** @type {GatewayConfiguration} */ (gateways[left]).endpoint
+      const second = /** @type {GatewayConfiguration} */ (gateways[right]).endpoint
+      if (first.relay === undefined || second.relay === undefined) continue
+      const sameAddress = first.relay.host === second.relay.host && first.relay.port === second.relay.port
+      const sameFactory = first.createPhysicalSocket === second.createPhysicalSocket
+      if (sameAddress && sameFactory) throw new TypeError("Multiple gateways cannot use the same unpinned endpoint/factory")
+    }
+  }
+  const defaultSpoolDirectory = join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "multiplexed-set")
+  if (options.spoolDirectory !== undefined && (typeof options.spoolDirectory !== "string" || options.spoolDirectory.length === 0)) throw new TypeError("spoolDirectory must be a non-empty string")
+  return {
+    gateways,
+    minimumReadyMembers,
+    maxPendingOpens,
+    limits,
+    memberOptions,
+    spoolDirectory: resolve(options.spoolDirectory === undefined ? defaultSpoolDirectory : options.spoolDirectory)
+  }
+}
+
+/**
+ * @param {string} baseId - Base identity.
+ * @param {string} gatewayId - Gateway identity.
+ */
+function deriveGatewayIdentity(baseId, gatewayId) {
+  const digest = createHash("sha256").update("socketduct-v3-transport-set\0").update(baseId).update("\0").update(gatewayId).digest("base64url")
+  return {connectionId: `gateway_${digest}`, spoolName: `gateway-${digest}`}
+}
+
+/**
+ * @param {unknown} value - Raw limit.
+ * @param {number} defaultValue - Default.
+ * @param {string} name - Option name.
+ */
+function positiveLimit(value, defaultValue, name) {
+  if (value === undefined) return defaultValue
+  if (!Number.isSafeInteger(value) || /** @type {number} */ (value) <= 0) throw new RangeError(`${name} must be a positive integer`)
+  return /** @type {number} */ (value)
+}
+
+/** @param {unknown} bytes - Reservation. */
+function validateReservation(bytes) {
+  if (!Number.isSafeInteger(bytes) || /** @type {number} */ (bytes) < 0) throw new RangeError("Socketduct transport-set budget reservations must be non-negative integers")
+}
+
+/** @param {unknown} options - Ordinary open options. */
+function validateOrdinaryOpenOptions(options) {
+  if (typeof options !== "object" || options === null) throw new TypeError("Virtual connection options are required")
+  if (Object.hasOwn(options, "gatewayId") || /** @type {{recover?: unknown}} */ (options).recover === true) {
+    throw new TypeError("Gateway-bound durable recovery must use recoverConnection before start")
+  }
+}
+
+/**
+ * @param {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Validated open options.
+ * @returns {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} Socket facade metadata.
+ */
+function normalizeVirtualSocketOptions(options) {
+  const target = options.target ?? {host: options.host, port: options.port}
+  if (typeof target.host !== "string" || target.host.length === 0 || target.host.length > 253 || !validPort(target.port)) throw new TypeError("Virtual connection target host and port are required")
+  return {
+    host: target.host,
+    port: target.port,
+    ...(options.allowHalfOpen === undefined ? {} : {allowHalfOpen: options.allowHalfOpen}),
+    ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
+    ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+  }
+}
+
+/** @param {unknown} member - Constructed member. */
+function validateMember(member) {
+  if (typeof member !== "object" || member === null) throw new TypeError("Transport-set member factory returned an invalid member")
+  const candidate = /** @type {Record<string, unknown>} */ (member)
+  if (typeof candidate.connect !== "function" || typeof candidate.createConnection !== "function" || typeof candidate.registerRecoveredConnection !== "function" || typeof candidate.status !== "function" || typeof candidate.close !== "function" || typeof candidate.detach !== "function" || typeof candidate.on !== "function") throw new TypeError("Transport-set member factory returned an invalid member")
+}
+
+/**
+ * @template {object} T
+ * @param {T} socket - Selected member socket.
+ * @param {string} gatewayId - Stable configured gateway ID.
+ * @returns {T & {readonly gatewayId: string}} Socket with immutable public allocation metadata.
+ */
+function exposeGateway(socket, gatewayId) {
+  const existing = Object.getOwnPropertyDescriptor(socket, "gatewayId")
+  if (existing !== undefined) {
+    if (existing.value !== gatewayId) throw new Error("Socketduct gateway allocation metadata mismatch")
+    return /** @type {T & {readonly gatewayId: string}} */ (socket)
+  }
+  Object.defineProperty(socket, "gatewayId", {value: gatewayId, enumerable: true, writable: false, configurable: false})
+  return /** @type {T & {readonly gatewayId: string}} */ (socket)
+}
+
+/**
+ * @template {object} T
+ * @param {T} socket - Socket whose assignment is owned by another socket.
+ * @param {() => string | undefined} gatewayId - Live immutable assignment lookup.
+ * @returns {T & {readonly gatewayId: string | undefined}} Socket with immutable public allocation metadata.
+ */
+function exposeGatewayGetter(socket, gatewayId) {
+  Object.defineProperty(socket, "gatewayId", {get: gatewayId, enumerable: true, configurable: false})
+  return /** @type {T & {readonly gatewayId: string | undefined}} */ (socket)
+}
+
+/**
+ * @param {GatewayVirtualSocket} socket - Deferred or selected virtual socket.
+ * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} callback - Completion.
+ */
+function installConnectCallback(socket, callback) {
+  let settled = false
+  const cleanup = () => {
+    socket.off("connect", onConnect)
+    socket.off("error", onError)
+  }
+  const onConnect = () => {
+    if (settled) return
+    settled = true
+    cleanup()
+    callback(null, socket)
+  }
+  /** @param {Error} error - Connection error. */
+  const onError = (error) => {
+    if (settled) return
+    settled = true
+    cleanup()
+    callback(error, socket)
+  }
+  socket.once("connect", onConnect)
+  socket.once("error", onError)
+}
+
+/** @param {Record<string, unknown>} options - Combined options. */
+function pickVirtualOptions(options) {
+  const keys = ["host", "port", "target", "sessionName", "identifier", "recover", "allowHalfOpen", "readableHighWaterMark", "writableHighWaterMark"]
+  return Object.fromEntries(keys.flatMap((key) => Object.hasOwn(options, key) ? [[key, options[key]]] : []))
+}
+
+/** @param {Record<string, unknown>} options - Combined options. */
+function omitVirtualOptions(options) {
+  const tlsOptions = {...options}
+  for (const key of ["host", "port", "target", "sessionName", "identifier", "recover", "allowHalfOpen", "readableHighWaterMark", "writableHighWaterMark"]) delete tlsOptions[key]
+  return tlsOptions
+}
+
+/**
+ * @param {GatewayTlsSocket} socket - TLS socket.
+ * @param {(error: Error | null, socket: GatewayTlsSocket) => void} callback - Completion.
+ */
+function installTlsCallback(socket, callback) {
+  let settled = false
+  const cleanup = () => {
+    socket.off("secureConnect", onConnect)
+    socket.off("error", onError)
+  }
+  const onConnect = () => {
+    if (settled) return
+    settled = true
+    cleanup()
+    callback(null, socket)
+  }
+  /** @param {Error} error - Connection error. */
+  const onError = (error) => {
+    if (settled) return
+    settled = true
+    cleanup()
+    callback(error, socket)
+  }
+  socket.once("secureConnect", onConnect)
+  socket.once("error", onError)
+}
+
+/** @returns {Error & {code: string}} */
+function closedError() {
+  return Object.assign(new Error("Multiplexed Socketduct transport set is closed"), {code: "SOCKETDUCT_TRANSPORT_SET_CLOSED"})
+}
+
+/** @returns {Error} Privacy-safe fallback for a member that closed without a cause. */
+function memberTerminalError() {
+  return Object.assign(new Error("Socketduct gateway member closed without a terminal cause"), {code: "SOCKETDUCT_MEMBER_TERMINAL"})
+}
+
+/** @param {Error | undefined} error - Internal terminal error. @returns {string | null} Stable privacy-safe code. */
+function publicErrorCode(error) {
+  if (error === undefined) return null
+  const code = /** @type {{code?: unknown}} */ (error).code
+  return typeof code === "string" && code.length <= 128 && /^[A-Z][A-Z0-9_]*$/.test(code) ? code : "SOCKETDUCT_MEMBER_TERMINAL"
+}
+
+/** @param {unknown} value - Thrown value. @returns {Error} */
+function asError(value) { return value instanceof Error ? value : new Error(String(value)) }
+
+/** @param {unknown} port - Raw port. @returns {port is number} */
+function validPort(port) { return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65_535 }