socketduct 0.1.15

package/src/client/multiplexed-connection.js

@@ -0,0 +1,1504 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns, jsdoc/require-returns-description */
+import {randomBytes} from "node:crypto"
+import {EventEmitter} from "node:events"
+import {readFileSync} from "node:fs"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {createConnection as netConnect} from "node:net"
+import {connect as tlsConnect} from "node:tls"
+
+import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
+import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
+import {SessionSpool} from "../spool/spool-file.js"
+import {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "./virtual-socket.js"
+
+const DEFAULT_WINDOW = 256 * 1024
+const DEFAULT_FRAME_BYTES = 16 * 1024
+const DEFAULT_STREAM_BYTES = 4 * 1024 * 1024
+const DEFAULT_CONNECTION_BYTES = 32 * 1024 * 1024
+const DEFAULT_MAX_STREAMS = 4096
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000
+const DEFAULT_SPOOL_MAX_AGE_MS = 24 * 60 * 60 * 1000
+const MANIFEST_PAGE_STREAMS = 64
+const MAX_CONTROL_QUEUE_BYTES = 1024 * 1024
+const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
+
+/**
+ * @typedef {object} MultiplexedConnectionOptions
+ * @property {{host: string, port: number, token: string}} relay - Authenticated relay endpoint.
+ * @property {{caFile?: string, certFile?: string, keyFile?: string, servername?: string, rejectUnauthorized?: boolean}} [tls] - Outer TLS settings.
+ * @property {string} [spoolDirectory] - Temporary replay spool root.
+ * @property {number} [maxAgeMs] - Maximum durable stream spool age, default 24 hours.
+ * @property {string} [connectionId] - Stable caller-owned identity required for recovery across client objects.
+ * @property {number} [initialWindowBytes] - Per-direction flow-control window.
+ * @property {number} [maxFrameBytes] - Maximum DATA payload.
+ * @property {number} [maxStreamBufferBytes] - Per-stream unacknowledged byte bound.
+ * @property {number} [maxConnectionBufferBytes] - Aggregate unacknowledged byte bound.
+ * @property {number} [maxStreams] - Concurrent stream bound.
+ * @property {number} [reconnectDelayMs] - Delay before the one shared reconnect.
+ * @property {number} [maxReconnectAttempts] - Bounded physical reconnect attempts.
+ * @property {number} [connectTimeoutMs] - Per-attempt physical/auth timeout.
+ * @property {number} [heartbeatIntervalMs] - Connection heartbeat interval, default 30 seconds.
+ * @property {number} [heartbeatTimeoutMs] - Missing-PONG reconnect threshold, default 90 seconds.
+ * @property {(options: {host: string, port: number, tls?: Record<string, unknown>}) => import('node:net').Socket} [createPhysicalSocket] - Test/custom transport factory.
+ * @property {boolean} [continuousReconnect] - Keep a warmed member reconnecting until explicitly closed.
+ * @property {{reserveData(bytes: number): void, releaseMemory(bytes: number): void, releaseSpool(bytes: number): void, reserveControl(bytes: number): void, releaseControl(bytes: number): void}} [aggregateBudget] - Optional process-wide set budget.
+ * @property {import('../logging/structured-logger.js').DiagnosticLogger} [logger] - Optional privacy-safe structured diagnostic logger.
+ * @typedef {object} VirtualConnectionOptions
+ * @property {string} [host] - Target host.
+ * @property {number} [port] - Target port.
+ * @property {{host: string, port: number}} [target] - Explicit target.
+ * @property {string} [sessionName] - Human-readable stream name.
+ * @property {string} [identifier] - Stable resumable identifier.
+ * @property {boolean} [recover] - Recover this stream from its existing durable v3 spool.
+ * @property {boolean} [allowHalfOpen] - Duplex half-close behavior.
+ * @property {number} [readableHighWaterMark] - Readable buffer threshold.
+ * @property {number} [writableHighWaterMark] - Writable buffer threshold.
+ * @typedef {{wire: Buffer, type: number, payloadBytes: number}} QueuedFrame
+ * @typedef {{sequence: number, data: Buffer}} ReplayChunk
+ * @typedef {object} ClientStream
+ * @property {number} id - Protocol stream ID.
+ * @property {string} identifier - Stable resume ID.
+ * @property {string} name - Human name.
+ * @property {{host: string, port: number}} target - Target endpoint.
+ * @property {VirtualSocket} socket - Public Duplex.
+ * @property {"opening" | "open" | "half-closed" | "closed" | "reset"} state - Lifecycle.
+ * @property {boolean} opened - Whether OPENED was observed.
+ * @property {boolean} openingSent - Whether OPEN was sent in this generation.
+ * @property {boolean} localEnded - Local writable EOF.
+ * @property {boolean} remoteEnded - Remote readable EOF.
+ * @property {boolean} remoteClosed - Relay terminal close.
+ * @property {number} sendSequence - Last locally allocated byte sequence.
+ * @property {number} sendAck - Last relay acknowledgement.
+ * @property {number} receiveSequence - Last contiguous relay byte sequence.
+ * @property {number} receiveAck - Last acknowledgement sent to relay.
+ * @property {number} sendWindow - Available peer receive window.
+ * @property {number} receiveUnackedBytes - Bytes delivered but not acknowledged.
+ * @property {number | undefined} pendingReceiveAck - Withheld ACK while readable backpressured.
+ * @property {number} bufferedBytes - Retained unacknowledged send bytes.
+ * @property {number} spoolReservedBytes - Shared budget retained until durable cleanup succeeds.
+ * @property {ReplayChunk[]} replay - Raw unacknowledged bytes.
+ * @property {QueuedFrame[]} queue - Fair-scheduler frames.
+ * @property {Promise<void>} spoolReady - Spool initialization.
+ * @property {Promise<void>} spoolQueue - Serialized append/truncate/remove work.
+ * @property {boolean} spoolRemovalQueued - Idempotent terminal cleanup flag.
+ * @property {Promise<void> | undefined} spoolRemovalPromise - Observable terminal cleanup result.
+ * @property {boolean} spoolCleanupFailureRecorded - Whether cleanup failure was counted.
+ * @property {boolean} ownsSpool - Whether terminal cleanup may remove this spool.
+ * @property {boolean} recoveredObject - Whether receive state came from a replaced client object.
+ * @typedef {object} ClientRecoveryState
+ * @property {number} version - Recovery schema version.
+ * @property {string} connectionId - Stable physical connection identity.
+ * @property {number} generation - Last authenticated generation.
+ * @property {number} streamId - Stable wire stream ID.
+ * @property {string} identifier - Stable stream identifier.
+ * @property {string} name - Human-readable stream name.
+ * @property {{host: string, port: number}} target - Authorized target identity.
+ * @property {boolean} opened - Whether the target was opened.
+ * @property {boolean} openingSent - Whether OPEN may have reached the relay.
+ * @property {boolean} localEnded - Whether local EOF was sent.
+ * @property {number} sendSequence - Highest durable client byte sequence.
+ * @property {number} sendAck - Highest relay-acknowledged client byte sequence.
+ * @property {number} receiveSequence - Highest accepted target byte sequence.
+ * @property {number} receiveAck - Highest durably acknowledged target byte sequence.
+ */
+
+/** One authenticated physical transport carrying many virtual TCP streams. */
+export class MultiplexedSocketductConnection extends EventEmitter {
+  /** @type {MultiplexedConnectionOptions} */
+  #options
+
+  /** @type {Map<number, ClientStream>} */
+  #streams = new Map()
+
+  /** @type {number} */
+  #nextStreamId = 1
+
+  /** @type {import('node:net').Socket | undefined} */
+  #physical
+
+  /** @type {Promise<void> | undefined} */
+  #connectPromise
+
+  /** @type {Promise<void> | undefined} */
+  #warmPromise
+
+  /** @type {(() => void) | undefined} */
+  #resolveConnect
+
+  /** @type {((error: Error) => void) | undefined} */
+  #rejectConnect
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  #reconnectTimer
+
+  /** @type {WeakMap<import('node:net').Socket, ReturnType<typeof setTimeout>>} */
+  #attemptTimers = new WeakMap()
+
+  /** @type {boolean} */
+  #closing = false
+
+  /** @type {boolean} */
+  #warm = false
+
+  /** @type {"configured" | "connecting" | "ready" | "reconnecting" | "disconnected" | "closed"} */
+  #physicalState = "configured"
+
+  /** @type {boolean} */
+  #preserveSpools = false
+
+  /** @type {boolean} */
+  #authenticated = false
+
+  /** @type {boolean} */
+  #hadAuthenticatedGeneration = false
+
+  /** @type {boolean} */
+  #resuming = false
+
+  /** @type {number} */
+  #generation = 0
+
+  /** @type {number} */
+  #reconnectAttempts = 0
+
+  /** @type {number} */
+  #reconnectAttemptTotal = 0
+
+  /** @type {number} */
+  #physicalConnects = 0
+
+  /** @type {number} */
+  #physicalAttempts = 0
+
+  /** @type {number} */
+  #reconnectSuccesses = 0
+
+  /** @type {number} */
+  #resumeFailures = 0
+
+  /** @type {Array<Record<string, unknown>>} */
+  #resumeResults = []
+
+  /** @type {number} */
+  #resumeNextPage = 0
+
+  /** @type {number} */
+  #aggregateBufferedBytes = 0
+
+  /** @type {number} */
+  #aggregateSpoolBytes = 0
+
+  /** @type {number} */
+  #spoolCleanupFailures = 0
+
+  /** @type {Set<Promise<void>>} */
+  #spoolCleanupTasks = new Set()
+
+  /** @type {Buffer[]} */
+  #controlQueue = []
+
+  /** @type {number} */
+  #controlQueuedBytes = 0
+
+  /** @type {boolean} */
+  #pumping = false
+
+  /** @type {number} */
+  #roundRobinCursor = 0
+
+  /** @type {Promise<void>} */
+  #openQueue = Promise.resolve()
+
+  /** @type {string} */
+  #connectionId
+
+  /** @type {ReturnType<typeof setInterval> | undefined} */
+  #heartbeatTimer
+
+  /** @type {number} */
+  #lastPongAt = 0
+
+  /** @type {number} */
+  #pingSequence = 0
+
+  /** @type {SessionSpool} */
+  #spool
+
+  /** @type {(options: {host: string, port: number, tls?: Record<string, unknown>}) => import('node:net').Socket} */
+  #createPhysicalSocket
+
+  /** @param {MultiplexedConnectionOptions} options - Connection and safety policy. */
+  constructor(options) {
+    super()
+    validateConnectionOptions(options)
+    this.#options = options
+    this.#connectionId = options.connectionId ?? randomBytes(24).toString("base64url")
+    const spoolDirectory = options.spoolDirectory ?? join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "multiplexed")
+    this.#spool = new SessionSpool({rootDir: spoolDirectory, maxBytes: this.#maxStreamBytes(), maxAgeMs: options.maxAgeMs ?? DEFAULT_SPOOL_MAX_AGE_MS})
+    this.#createPhysicalSocket = options.createPhysicalSocket ?? createPhysicalSocket
+    this.createConnection = this.createConnection.bind(this)
+  }
+
+  /**
+   * Warms and authenticates this member without allocating a target stream.
+   * Concurrent calls share the same physical connection promise.
+   * @returns {Promise<void>} Resolves when the member becomes ready.
+   */
+  connect() {
+    if (this.#closing) return Promise.reject(Object.assign(new Error("Multiplexed Socketduct connection is closed"), {code: "SOCKETDUCT_CONNECTION_CLOSED"}))
+    if (this.#warmPromise !== undefined) return this.#warmPromise
+    this.#warm = true
+    this.#warmPromise = Promise.all([...this.#streams.values()].map((stream) => stream.spoolReady)).then(() => this.#ensureConnected())
+    return this.#warmPromise
+  }
+
+  /**
+   * Allocates a virtual stream without allocating another physical transport.
+   * @param {VirtualConnectionOptions} options - Target/socket options.
+   * @param {(error: Error | null, socket: VirtualSocket) => void} [callback] - Node-style optional callback.
+   * @returns {VirtualSocket} Socket-shaped Duplex.
+   */
+  createConnection(options, callback) {
+    return this.#createConnection(options, callback, true)
+  }
+
+  /**
+   * Registers durable recovery state without starting a physical attempt.
+   * @param {VirtualConnectionOptions} options - Recovery options.
+   * @param {(error: Error | null, socket: VirtualSocket) => void} [callback] - Node-style optional callback.
+   * @returns {VirtualSocket} Cold registered socket.
+   */
+  registerRecoveredConnection(options, callback) {
+    if (options.recover !== true) throw new TypeError("registerRecoveredConnection requires recover: true")
+    return this.#createConnection(options, callback, false)
+  }
+
+  /**
+   * @param {VirtualConnectionOptions} options - Target/socket options.
+   * @param {((error: Error | null, socket: VirtualSocket) => void) | undefined} callback - Node-style optional callback.
+   * @param {boolean} connectOnReady - Whether creation should start the physical connection.
+   * @returns {VirtualSocket} Socket-shaped Duplex.
+   */
+  #createConnection(options, callback, connectOnReady) {
+    if (this.#closing) throw new Error("Multiplexed Socketduct connection is closed")
+    if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum virtual stream count exceeded")
+    const target = normalizeTarget(options)
+    const identifier = options.identifier ?? randomBytes(24).toString("base64url")
+    if (!STABLE_IDENTIFIER.test(identifier)) throw new TypeError("Virtual stream identifier must be 8-128 URL-safe opaque characters")
+    const recovery = options.recover === true
+      ? validateRecoveryState(this.#spool.readRecoveryStateSync(identifier, "edge-v3"), {
+        connectionId: this.#connectionId,
+        identifier,
+        target,
+        ...(options.sessionName === undefined ? {} : {sessionName: options.sessionName})
+      })
+      : undefined
+    if (recovery !== undefined && this.#physicalAttempts > 0) throw new Error("Recovered streams must be registered before the replacement physical connection starts")
+    const id = recovery?.streamId ?? this.#allocateStreamId()
+    if (this.#streams.has(id)) throw new Error(`V3 stream ID ${id} is already active`)
+    if (recovery !== undefined) {
+      this.#nextStreamId = Math.max(this.#nextStreamId, id + 2)
+      this.#generation = Math.max(this.#generation, recovery.generation)
+      this.#hadAuthenticatedGeneration = true
+    }
+    const name = options.sessionName ?? recovery?.name ?? `socketduct-v3-${id}`
+    if (typeof name !== "string" || name.length === 0 || name.length > 256) throw new TypeError("Virtual stream name must be 1-256 characters")
+    const socketOptions = {
+      ...target,
+      ...(options.allowHalfOpen === undefined ? {} : {allowHalfOpen: options.allowHalfOpen}),
+      ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
+      ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+    }
+    const socket = new VirtualSocket(this, id, socketOptions)
+    const stream = /** @type {ClientStream} */ ({
+      id,
+      identifier,
+      name,
+      target,
+      socket,
+      state: recovery?.localEnded === true ? "half-closed" : (recovery?.opened === true ? "open" : "opening"),
+      opened: recovery?.opened ?? false,
+      openingSent: recovery?.openingSent ?? false,
+      localEnded: recovery?.localEnded ?? false,
+      remoteEnded: false,
+      remoteClosed: false,
+      sendSequence: recovery?.sendSequence ?? 0,
+      sendAck: recovery?.sendAck ?? 0,
+      // A replacement VirtualSocket cannot inherit bytes buffered only by the
+      // previous object; restart delivery at the durable acknowledgement.
+      receiveSequence: recovery?.receiveAck ?? 0,
+      receiveAck: recovery?.receiveAck ?? 0,
+      sendWindow: this.#initialWindow(),
+      receiveUnackedBytes: 0,
+      pendingReceiveAck: undefined,
+      bufferedBytes: 0,
+      spoolReservedBytes: 0,
+      replay: [],
+      queue: [],
+      spoolReady: Promise.resolve(),
+      spoolQueue: Promise.resolve(),
+      spoolRemovalQueued: false,
+      spoolRemovalPromise: undefined,
+      spoolCleanupFailureRecorded: false,
+      ownsSpool: recovery !== undefined,
+      recoveredObject: recovery !== undefined
+    })
+    stream.spoolReady = recovery === undefined
+      ? this.#spool.createNew({sessionId: identifier, ownerId: "edge-v3"})
+        .then(() => {
+          stream.ownsSpool = true
+          return this.#spool.writeRecoveryState(identifier, this.#recoveryState(stream))
+        })
+      : this.#spool.readChunksAfter(identifier, stream.sendAck).then((chunks) => {
+        validateRecoveredChunks(stream, chunks, this.#maxStreamBytes())
+        if (this.#streams.get(stream.id) !== stream) return
+        const bufferedBytes = chunks.reduce((sum, chunk) => sum + chunk.data.length, 0)
+        if (this.#aggregateBufferedBytes + bufferedBytes > this.#maxConnectionBytes()) throw new Error("Recovered Socketduct data exceeds the connection buffer limit")
+        this.#options.aggregateBudget?.reserveData(bufferedBytes)
+        stream.replay = chunks
+        stream.bufferedBytes = bufferedBytes
+        stream.spoolReservedBytes = bufferedBytes
+        this.#aggregateBufferedBytes += bufferedBytes
+        this.#aggregateSpoolBytes += bufferedBytes
+      })
+    stream.spoolQueue = stream.spoolReady.catch(() => {})
+    this.#streams.set(id, stream)
+    logDiagnostic(this.#options.logger, "virtual_stream.opening", {
+      streamId: id,
+      generation: this.#generation,
+      recovered: recovery !== undefined
+    })
+    if (callback !== undefined) installConnectCallback(socket, callback)
+    if (connectOnReady) {
+      stream.spoolReady
+        .then(() => this.#streams.get(stream.id) === stream && !stream.socket.destroyed ? this.#ensureConnected() : undefined)
+        .then(() => this.#openStream(stream))
+        .catch((error) => socket._receiveError(asError(error)))
+    } else {
+      stream.spoolReady.catch((error) => socket._receiveError(asError(error)))
+    }
+    return socket
+  }
+
+  /** @returns {{physicalState: string, connectionGeneration: number, virtualStreams: number, streamStates: Record<string, number>, queuedBytes: number, dataQueuedBytes: number, controlQueuedBytes: number, spoolBytes: number, spoolCleanupFailures: number, physicalConnects: number, reconnectAttempts: number, reconnectSuccesses: number, resumeFailures: number}} Privacy-safe status. */
+  status() {
+    /** @type {Record<string, number>} */
+    const streamStates = {}
+    for (const stream of this.#streams.values()) {
+      streamStates[stream.state] = (streamStates[stream.state] ?? 0) + 1
+    }
+    return {
+      physicalState: this.#physicalState,
+      connectionGeneration: this.#generation,
+      virtualStreams: this.#streams.size,
+      streamStates,
+      queuedBytes: this.#aggregateBufferedBytes + this.#controlQueuedBytes,
+      dataQueuedBytes: this.#aggregateBufferedBytes,
+      controlQueuedBytes: this.#controlQueuedBytes,
+      spoolBytes: this.#aggregateSpoolBytes,
+      spoolCleanupFailures: this.#spoolCleanupFailures,
+      physicalConnects: this.#physicalConnects,
+      reconnectAttempts: this.#reconnectAttemptTotal,
+      reconnectSuccesses: this.#reconnectSuccesses,
+      resumeFailures: this.#resumeFailures
+    }
+  }
+
+  /** @returns {{address?: string, port?: number}} Current physical local address. */
+  physicalAddress() {
+    const address = this.#physical?.localAddress
+    const port = this.#physical?.localPort
+    return {
+      ...(address === undefined ? {} : {address}),
+      ...(port === undefined ? {} : {port})
+    }
+  }
+
+  /** @returns {this} */
+  ref() {
+    this.#physical?.ref()
+    this.#reconnectTimer?.ref?.()
+    return this
+  }
+
+  /** @returns {this} */
+  unref() {
+    this.#physical?.unref()
+    this.#reconnectTimer?.unref?.()
+    return this
+  }
+
+  /** Gracefully closes all virtual streams and the shared transport. @returns {Promise<void>} */
+  async close() {
+    if (this.#closing) return
+    this.#closing = true
+    this.#setPhysicalState("closed")
+    if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = undefined
+    this.#stopHeartbeat()
+    this.#clearControlQueue()
+    if (this.#physical !== undefined && !this.#physical.destroyed && this.#authenticated) {
+      try {
+        this.#physical.end(encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({reason: "client_close"})))
+      } catch {
+        this.#physical.destroy()
+      }
+    }
+    /** @type {Error[]} */
+    const cleanupErrors = []
+    for (const stream of [...this.#streams.values()]) {
+      stream.remoteClosed = true
+      if (!stream.socket.destroyed) stream.socket.destroy()
+      if (stream.ownsSpool) {
+        try {
+          await this.#removeSpool(stream)
+        } catch (error) {
+          const cleanupError = asError(error)
+          this.#handleSpoolCleanupFailure(stream, cleanupError)
+          cleanupErrors.push(cleanupError)
+        }
+      }
+    }
+    const pendingResults = await Promise.allSettled([...this.#spoolCleanupTasks])
+    for (const result of pendingResults) {
+      if (result.status === "rejected") {
+        const cleanupError = asError(result.reason)
+        if (!cleanupErrors.includes(cleanupError)) cleanupErrors.push(cleanupError)
+      }
+    }
+    this.#streams.clear()
+    this.#physical?.destroy()
+    this.#physical = undefined
+    this.#authenticated = false
+    this.#rejectConnect?.(new Error("Multiplexed Socketduct connection closed"))
+    this.#settleConnect()
+    if (cleanupErrors.length > 0) throw new AggregateError(cleanupErrors, "Socketduct durable spool cleanup failed")
+  }
+
+  /**
+   * Detaches the physical transport while preserving active stream spools for
+   * a new connection object using the same caller-provided connectionId.
+   * @returns {Promise<void>} Resolves after recovery state is durable.
+   */
+  async detach() {
+    if (this.#closing) return
+    if (this.#options.connectionId === undefined) throw new Error("detach() requires an explicit stable connectionId")
+    this.#preserveSpools = true
+    this.#closing = true
+    this.#setPhysicalState("closed")
+    if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = undefined
+    this.#stopHeartbeat()
+    try {
+      await Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream)))
+      if (this.#streams.size === 0 && this.#physical !== undefined && !this.#physical.destroyed && this.#authenticated) {
+        const physical = this.#physical
+        await new Promise((resolve) => {
+          physical.once("close", resolve)
+          physical.end(encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({reason: "client_detach_empty"})))
+        })
+      }
+    } finally {
+      this.#physical?.destroy()
+      this.#physical = undefined
+      this.#authenticated = false
+      this.#rejectConnect?.(new SocketductSessionLostError("Socketduct connection detached for durable recovery", "CONNECTION_DETACHED"))
+      this.#settleConnect()
+    }
+  }
+
+  /**
+   * @param {number} streamId - Stream. @param {Buffer} data - Bytes. @param {(error?: Error | null) => void} callback - Completion. @returns {void}
+   * @param data
+   * @param callback
+   */
+  _writeStream(streamId, data, callback) {
+    const stream = this.#streams.get(streamId)
+    if (this.#closing || stream === undefined || stream.state === "closed" || stream.state === "reset" || stream.localEnded) {
+      callback(new SocketductStreamError("Virtual stream is not writable", "ERR_STREAM_DESTROYED"))
+      return
+    }
+    if (stream.sendSequence > Number.MAX_SAFE_INTEGER - data.length) {
+      callback(new SocketductStreamError("Virtual stream sequence space exhausted", "SEQUENCE_EXHAUSTED"))
+      return
+    }
+    if (stream.bufferedBytes + data.length > this.#maxStreamBytes() || this.#aggregateBufferedBytes + data.length > this.#maxConnectionBytes()) {
+      const error = new SocketductStreamError("Socketduct stream buffer limit exceeded", "SOCKETDUCT_BUFFER_LIMIT")
+      callback(error)
+      return
+    }
+    try {
+      this.#options.aggregateBudget?.reserveData(data.length)
+    } catch (error) {
+      callback(asError(error))
+      return
+    }
+    /** @type {ReplayChunk[]} */
+    const chunks = []
+    for (let offset = 0; offset < data.length; offset += this.#maxFrameBytes()) {
+      const part = Buffer.from(data.subarray(offset, Math.min(data.length, offset + this.#maxFrameBytes())))
+      stream.sendSequence += part.length
+      chunks.push({sequence: stream.sendSequence, data: part})
+    }
+    stream.replay.push(...chunks)
+    stream.bufferedBytes += data.length
+    stream.spoolReservedBytes += data.length
+    this.#aggregateBufferedBytes += data.length
+    this.#aggregateSpoolBytes += data.length
+    const persist = async () => {
+      await this.#queueSpoolOperation(stream, async () => {
+        for (const chunk of chunks) {
+          await this.#spool.appendChunk({sessionId: stream.identifier, ownerId: "edge-v3", sequence: chunk.sequence, data: chunk.data})
+        }
+        await this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream))
+      })
+      if (this.#streams.get(stream.id) === stream) for (const chunk of chunks) this.#queueData(stream, chunk)
+    }
+    persist().then(() => callback(), (error) => callback(asError(error)))
+  }
+
+  /**
+   * @param {number} streamId - Stream. @param {(error?: Error | null) => void} callback - Completion. @returns {void}
+   * @param callback
+   */
+  _endStream(streamId, callback) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined || stream.localEnded) {
+      callback()
+      return
+    }
+    stream.localEnded = true
+    stream.state = "half-closed"
+    this.#persistStreamState(stream).then(() => {
+      this.#queueStreamControl(stream, V3FrameType.END, stream.sendSequence)
+      callback()
+    }, (error) => callback(asError(error)))
+  }
+
+  /**
+   * @param {number} streamId - Stream. @param {Error | null} error - Cause. @returns {void}
+   * @param error
+   */
+  _destroyStream(streamId, error) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined) return
+    this.#streams.delete(streamId)
+    this.#aggregateBufferedBytes = Math.max(0, this.#aggregateBufferedBytes - stream.bufferedBytes)
+    this.#options.aggregateBudget?.releaseMemory(stream.bufferedBytes)
+    stream.state = error === null ? "closed" : "reset"
+    logDiagnostic(this.#options.logger, error === null ? "virtual_stream.closed" : "virtual_stream.error", {
+      streamId,
+      generation: this.#generation,
+      ...(error === null ? {} : errorDiagnostics(error))
+    })
+    if (!stream.remoteClosed && this.#authenticated && !this.#resuming) {
+      this.#queueControlFrame(V3FrameType.RESET, streamId, 0, {
+        code: error instanceof SocketductStreamError ? error.code : "CLIENT_CANCELLED"
+      })
+    }
+    if (!this.#preserveSpools) {
+      this.#trackSpoolCleanup(stream)
+    }
+    if (this.#streams.size === 0 && !this.#authenticated && this.#physical !== undefined) this.#physical.destroy()
+  }
+
+  /** @param {number} streamId - Stream. @returns {void} */
+  _resumeReadable(streamId) {
+    const stream = this.#streams.get(streamId)
+    if (stream?.pendingReceiveAck === undefined) return
+    const ack = stream.pendingReceiveAck
+    stream.pendingReceiveAck = undefined
+    this.#ackReceived(stream, ack)
+  }
+
+  /** @returns {number} */
+  #allocateStreamId() {
+    const id = this.#nextStreamId
+    if (id > 0xffff_fffd) throw new Error("V3 stream ID space exhausted for this connection generation")
+    this.#nextStreamId += 2
+    return id
+  }
+
+  /** @returns {Promise<void>} */
+  #ensureConnected() {
+    if (this.#authenticated && !this.#resuming && this.#physical !== undefined && !this.#physical.destroyed) return Promise.resolve()
+    if (this.#connectPromise !== undefined) return this.#connectPromise
+    this.#connectPromise = new Promise((resolve, reject) => {
+      this.#resolveConnect = resolve
+      this.#rejectConnect = reject
+    })
+    this.#connectPhysical()
+    return this.#connectPromise
+  }
+
+  /** @returns {void} */
+  #connectPhysical() {
+    if (this.#closing) return
+    const wasConnected = this.#hadAuthenticatedGeneration
+    const retryAttempt = this.#physicalAttempts > 0
+    logDiagnostic(this.#options.logger, "transport.connecting", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts + 1,
+      reconnect: wasConnected || retryAttempt
+    })
+    this.#setPhysicalState(wasConnected || retryAttempt ? "reconnecting" : "connecting")
+    this.#physicalAttempts += 1
+    if (retryAttempt) {
+      this.#reconnectAttempts += 1
+      this.#reconnectAttemptTotal += 1
+    }
+    let physical
+    try {
+      physical = this.#createPhysicalSocket({
+        host: this.#options.relay.host,
+        port: this.#options.relay.port,
+        ...(this.#options.tls === undefined ? {} : {tls: resolveTls(this.#options.tls)})
+      })
+    } catch (error) {
+      this.#failAttempt(asError(error), true)
+      return
+    }
+    this.#physical = physical
+    this.#authenticated = false
+    this.#resuming = wasConnected
+    const decoderLimit = Math.max(64 * 1024, this.#maxFrameBytes())
+    const decoder = new V3FrameDecoder({maxFrameBytes: decoderLimit, maxBufferedBytes: decoderLimit * 2})
+    const readyEvent = this.#options.tls === undefined ? "connect" : "secureConnect"
+    /** @type {Error & {code?: string} | undefined} */
+    let attemptError
+    const timer = setTimeout(() => {
+      attemptError = Object.assign(new Error("Socketduct v3 connect/auth timeout"), {code: "SOCKETDUCT_AUTH_TIMEOUT"})
+      physical.destroy(attemptError)
+    }, this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
+    this.#attemptTimers.set(physical, timer)
+    timer.unref?.()
+    const onReady = () => {
+      if (this.#physical !== physical || this.#closing) return
+      this.#generation += 1
+      this.#physicalConnects += 1
+      const generation = this.#generation
+      // Persist the attempted generation before AUTH can reach the relay. A
+      // crash after AUTH but before AUTH_OK can then advance past it safely.
+      void Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream))).then(() => {
+        if (this.#physical !== physical || physical.destroyed || this.#closing) return
+        const auth = encodeV3Control({
+          token: this.#options.relay.token,
+          versions: [3],
+          connectionId: this.#connectionId,
+          generation,
+          initialWindow: this.#initialWindow(),
+          compression: []
+        })
+        physical.write(encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: generation}, auth))
+      }, (error) => physical.destroy(asError(error)))
+    }
+    physical.once(readyEvent, onReady)
+    physical.on("data", (chunk) => {
+      let frames
+      try {
+        frames = decoder.push(chunk)
+      } catch (error) {
+        physical.destroy(asError(error))
+        return
+      }
+      for (const frame of frames) {
+        try {
+          this.#handleFrame(frame, physical)
+        } catch (error) {
+          physical.destroy(asError(error))
+        }
+      }
+    })
+    physical.once("error", (error) => {
+      attemptError = error
+      if (isFatalTransportError(error)) this.#failAll(error)
+    })
+    physical.once("close", () => {
+      this.#clearAttemptTimeout(physical)
+      if (this.#physical !== physical) return
+      this.#physical = undefined
+      this.#authenticated = false
+      this.#stopHeartbeat()
+      this.#clearControlQueue()
+      this.#roundRobinCursor = 0
+      for (const stream of this.#streams.values()) {
+        stream.queue = []
+      }
+      if (this.#closing) return
+      logDiagnostic(this.#options.logger, "transport.disconnected", {
+        generation: this.#generation,
+        virtualStreams: this.#streams.size,
+        ...errorDiagnostics(attemptError, "TRANSPORT_CLOSED")
+      })
+      if (this.#streams.size === 0 && !this.#warm) {
+        this.#setPhysicalState("disconnected")
+        this.#rejectConnect?.(attemptError ?? new Error("Socketduct physical attempt closed"))
+        this.#settleConnect()
+        return
+      }
+      if (attemptError?.code === "SOCKETDUCT_AUTH_TIMEOUT" && !this.#hadAuthenticatedGeneration && this.#options.continuousReconnect !== true) {
+        this.#setPhysicalState("disconnected")
+        this.#rejectConnect?.(attemptError)
+        this.#settleConnect()
+        for (const stream of [...this.#streams.values()]) stream.socket._receiveError(attemptError)
+        return
+      }
+      this.#scheduleReconnect()
+    })
+  }
+
+  /**
+   * @param {import('../protocol/v3-frame.js').V3Frame} frame - Decoded frame. @param {import('node:net').Socket} physical - Source. @returns {void}
+   * @param physical
+   */
+  #handleFrame(frame, physical) {
+    if (this.#physical !== physical) return
+    if (frame.type === V3FrameType.AUTH_OK) {
+      // Attempt timeout ownership extends through AUTH_OK.
+      this.#clearAttemptTimeout(physical)
+      if (this.#authenticated) throw new Error("Relay repeated V3 authentication")
+      const control = decodeV3Control(frame.payload)
+      if (control.version !== 3 || control.connectionId !== this.#connectionId || control.generation !== this.#generation || typeof control.resumed !== "boolean") throw new Error("Relay did not negotiate Socketduct protocol v3")
+      if (this.#resuming && control.resumed === false) {
+        const hasResumeState = [...this.#streams.values()].some((stream) => stream.opened || stream.openingSent)
+        if (hasResumeState) {
+          this.#failAll(new SocketductSessionLostError("Relay lost the multiplexed connection resume state", "CONNECTION_RESUME_LOST"))
+          return
+        }
+        this.#resuming = false
+      } else if (!this.#resuming && control.resumed === true) {
+        // The previous AUTH may have reached the relay even when AUTH_OK did not
+        // reach this client. Complete an empty/partial manifest safely.
+        this.#resuming = true
+      }
+      this.#hadAuthenticatedGeneration = true
+      this.#authenticated = true
+      void this.#finishAuthenticatedGeneration(physical).catch((error) => physical.destroy(asError(error)))
+      return
+    }
+    if (frame.type === V3FrameType.AUTH_ERROR || frame.type === V3FrameType.GOAWAY) {
+      const detail = decodeV3Control(frame.payload)
+      const code = typeof detail.code === "string" ? detail.code : "AUTH_FAILED"
+      this.#failAll(new SocketductSessionLostError("Socketduct physical connection was rejected", code))
+      return
+    }
+    if (!this.#authenticated) throw new Error("V3 frame received before authentication")
+    if (frame.type === V3FrameType.PING) {
+      this.#queueControlFrame(V3FrameType.PONG, 0, frame.sequence, {})
+      return
+    }
+    if (frame.type === V3FrameType.PONG) {
+      this.#lastPongAt = Date.now()
+      return
+    }
+    if (frame.type === V3FrameType.RESUMED) {
+      if (!this.#resuming) throw new Error("Unexpected V3 resume response")
+      const manifest = decodeV3Control(frame.payload)
+      if (manifest.page !== this.#resumeNextPage || !Array.isArray(manifest.streams)) throw new Error("Invalid paginated V3 resume response")
+      this.#resumeNextPage += 1
+      this.#resumeResults.push(...manifest.streams.filter((item) => typeof item === "object" && item !== null))
+      if (manifest.final !== true) return
+      for (const item of this.#resumeResults) this.#applyResumeResult(item)
+      this.#resumeResults = []
+      this.#resuming = false
+      this.#reconnectSuccesses += 1
+      this.#roundRobinCursor = 0
+      for (const stream of this.#streams.values()) {
+        if (!stream.opened) continue
+        stream.queue = stream.queue.filter((entry) => entry.type !== V3FrameType.DATA)
+        for (const chunk of stream.replay) {
+          if (chunk.sequence > stream.sendAck) this.#queueData(stream, chunk)
+        }
+        if (stream.localEnded) this.#queueStreamControl(stream, V3FrameType.END, stream.sendSequence)
+      }
+      this.#completeConnection()
+      return
+    }
+    const stream = this.#streams.get(frame.streamId)
+    if (stream === undefined) {
+      if (frame.type !== V3FrameType.CLOSE && frame.type !== V3FrameType.RESET) this.#queueControlFrame(V3FrameType.RESET, frame.streamId, 0, {code: "UNKNOWN_STREAM"})
+      return
+    }
+    if (frame.type === V3FrameType.OPENED) {
+      const detail = decodeV3Control(frame.payload)
+      if (detail.identifier !== stream.identifier) throw new Error("Relay opened response identifier mismatch")
+      stream.opened = true
+      stream.state = "open"
+      logDiagnostic(this.#options.logger, "virtual_stream.opened", {
+        streamId: stream.id,
+        generation: this.#generation,
+        recovered: false
+      })
+      stream.sendWindow = typeof detail.initialWindow === "number" ? Math.min(detail.initialWindow, this.#initialWindow()) : this.#initialWindow()
+      void this.#persistStreamState(stream).then(() => {
+        if (this.#streams.get(stream.id) !== stream) return
+        stream.socket._markConnected()
+        if (!stream.queue.some((entry) => entry.type === V3FrameType.DATA)) {
+          for (const chunk of stream.replay) if (chunk.sequence > stream.sendAck) this.#queueData(stream, chunk)
+        }
+        this.#schedulePump()
+      }, (error) => stream.socket._receiveError(asError(error)))
+      return
+    }
+    if (frame.type === V3FrameType.DATA) {
+      if (frame.flags !== 0) throw new Error("V3 DATA compression was not negotiated")
+      const expected = stream.receiveSequence + frame.payload.length
+      if (frame.sequence !== expected || frame.payload.length > this.#maxFrameBytes()) throw new Error("Non-contiguous or oversized V3 stream data")
+      stream.receiveSequence = frame.sequence
+      stream.receiveUnackedBytes += frame.payload.length
+      if (stream.receiveUnackedBytes > this.#initialWindow()) throw new Error("V3 peer exceeded receive window")
+      const canContinue = stream.socket._receive(frame.payload)
+      if (canContinue) this.#ackReceived(stream, frame.sequence)
+      else stream.pendingReceiveAck = frame.sequence
+      return
+    }
+    if (frame.type === V3FrameType.ACK) {
+      this.#applyAck(stream, frame.sequence)
+      return
+    }
+    if (frame.type === V3FrameType.WINDOW) {
+      if (frame.sequence > this.#initialWindow()) throw new Error("Invalid V3 window update")
+      stream.sendWindow = Math.min(this.#initialWindow(), stream.sendWindow + frame.sequence)
+      this.#schedulePump()
+      return
+    }
+    if (frame.type === V3FrameType.END) {
+      stream.remoteEnded = true
+      stream.socket._receiveEnd()
+      return
+    }
+    if (frame.type === V3FrameType.CLOSE) {
+      // CLOSE is terminal but acknowledged symmetrically. Keep the reply in the
+      // connection control queue so VirtualSocket auto-destruction cannot drop it.
+      this.#queueControlFrame(V3FrameType.CLOSE, stream.id, frame.sequence, {})
+      stream.remoteClosed = true
+      stream.state = "closed"
+      stream.socket._receiveEnd()
+      return
+    }
+    if (frame.type === V3FrameType.RESET) {
+      const detail = decodeV3Control(frame.payload)
+      const code = typeof detail.code === "string" ? detail.code : "STREAM_RESET"
+      stream.remoteClosed = true
+      stream.state = "reset"
+      const lost = code.startsWith("RESUME_") || code === "SESSION_LOST" || code.includes("UNCERTAIN")
+      stream.socket._receiveError(lost
+        ? new SocketductSessionLostError("Virtual stream could not be resumed", code)
+        : new SocketductStreamError("Virtual stream was reset by relay", code))
+      return
+    }
+    throw new Error(`Unsupported V3 frame type from relay: ${frame.type}`)
+  }
+
+  /**
+   * Makes the authenticated generation durable before opening or resuming.
+   * @param {import('node:net').Socket} physical - Attempt owner.
+   * @returns {Promise<void>} Completion.
+   */
+  async #finishAuthenticatedGeneration(physical) {
+    await Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream)))
+    if (this.#physical !== physical || physical.destroyed || !this.#authenticated) return
+    if (!this.#resuming) {
+      this.#completeConnection()
+      return
+    }
+    const streams = [...this.#streams.values()].filter((stream) => stream.opened || stream.openingSent).map((stream) => ({
+      streamId: stream.id,
+      identifier: stream.identifier,
+      clientToTargetAck: stream.sendAck,
+      // A surviving VirtualSocket still owns bytes accepted into its readable
+      // buffer. A replacement object owns only its durable acknowledgement.
+      targetToClientAck: stream.recoveredObject ? stream.receiveAck : stream.receiveSequence,
+      localEnded: stream.localEnded
+    }))
+    this.#resumeResults = []
+    this.#resumeNextPage = 0
+    const pageCount = Math.max(1, Math.ceil(streams.length / MANIFEST_PAGE_STREAMS))
+    for (let page = 0; page < pageCount; page += 1) {
+      this.#queueControlFrame(V3FrameType.RESUME, 0, this.#generation, {
+        page,
+        final: page === pageCount - 1,
+        streams: streams.slice(page * MANIFEST_PAGE_STREAMS, (page + 1) * MANIFEST_PAGE_STREAMS)
+      })
+    }
+  }
+
+  /** @param {unknown} item - Resume item. @returns {void} */
+  #applyResumeResult(item) {
+    if (typeof item !== "object" || item === null) return
+    const result = /** @type {{streamId?: unknown, status?: unknown, opened?: unknown, clientToTargetAck?: unknown, targetToClientAck?: unknown, code?: unknown}} */ (item)
+    if (typeof result.streamId !== "number") return
+    const stream = this.#streams.get(result.streamId)
+    if (stream === undefined) return
+    if (result.status !== "resumed") {
+      this.#resumeFailures += 1
+      stream.remoteClosed = true
+      stream.socket._receiveError(new SocketductSessionLostError("Virtual stream could not be resumed", typeof result.code === "string" ? result.code : "RESUME_REJECTED"))
+      return
+    }
+    if (typeof result.clientToTargetAck === "number") this.#applyAck(stream, result.clientToTargetAck)
+    if (typeof result.targetToClientAck === "number" && result.targetToClientAck > stream.receiveSequence) throw new Error("Relay resume acknowledgement exceeds received sequence")
+    if (typeof result.targetToClientAck === "number") {
+      stream.receiveAck = Math.max(stream.receiveAck, result.targetToClientAck)
+      stream.receiveUnackedBytes = Math.max(0, stream.receiveSequence - stream.receiveAck)
+      if (stream.pendingReceiveAck !== undefined && stream.pendingReceiveAck <= stream.receiveAck) stream.pendingReceiveAck = undefined
+    }
+    // Window credit belongs to a physical generation. Recompute it from the
+    // acknowledged durable replay set instead of retaining spent old credit.
+    stream.sendWindow = this.#initialWindow()
+    if (result.opened === true) stream.opened = true
+    stream.openingSent = true
+    stream.recoveredObject = false
+    void this.#persistStreamState(stream).catch((error) => stream.socket._receiveError(asError(error)))
+  }
+
+  /** @param {ClientStream} stream - Stream. @returns {void} */
+  #openStream(stream) {
+    if (stream.socket.destroyed || stream.opened || stream.openingSent) return
+    stream.openingSent = true
+    const open = this.#openQueue.then(() => this.#persistStreamState(stream)).then(() => {
+      if (this.#streams.get(stream.id) !== stream || stream.socket.destroyed) return
+      this.#queueControlFrame(V3FrameType.OPEN, stream.id, 0, {
+        identifier: stream.identifier,
+        name: stream.name,
+        target: stream.target,
+        initialWindow: this.#initialWindow()
+      })
+    })
+    this.#openQueue = open.catch(() => {})
+    void open.catch((error) => stream.socket._receiveError(asError(error)))
+  }
+
+  /**
+   * @param {ClientStream} stream - Stream. @param {ReplayChunk} chunk - Raw bytes. @returns {void}
+   * @param chunk
+   */
+  #queueData(stream, chunk) {
+    const wire = encodeV3Frame({type: V3FrameType.DATA, streamId: stream.id, sequence: chunk.sequence}, chunk.data)
+    stream.queue.push({wire, type: V3FrameType.DATA, payloadBytes: chunk.data.length})
+    this.#schedulePump()
+  }
+
+  /**
+   * @param {ClientStream} stream - Stream. @param {number} type - Frame type. @param {number} sequence - Position. @returns {void}
+   * @param type
+   * @param sequence
+   */
+  #queueStreamControl(stream, type, sequence) {
+    stream.queue.push({wire: encodeV3Frame({type, streamId: stream.id, sequence}), type, payloadBytes: 0})
+    this.#schedulePump()
+  }
+
+  /**
+   * @param {number} type - Frame type. @param {number} streamId - Stream ID. @param {number} sequence - Position. @param {Record<string, unknown>} value - Control body. @returns {void}
+   * @param streamId
+   * @param sequence
+   * @param value
+   */
+  #queueControlFrame(type, streamId, sequence, value) {
+    if (this.#closing) return
+    const wire = encodeV3Frame({type, streamId, sequence}, encodeV3Control(value))
+    if (this.#controlQueuedBytes + wire.length > MAX_CONTROL_QUEUE_BYTES) {
+      this.#failAll(new SocketductSessionLostError("Socketduct control queue limit exceeded", "CONTROL_QUEUE_LIMIT"))
+      return
+    }
+    try {
+      this.#options.aggregateBudget?.reserveControl(wire.length)
+    } catch (error) {
+      this.#failAll(asError(error))
+      return
+    }
+    this.#controlQueue.push(wire)
+    this.#controlQueuedBytes += wire.length
+    this.#schedulePump()
+  }
+
+  /** @returns {void} */
+  #schedulePump() {
+    if (this.#pumping || !this.#authenticated || this.#physical === undefined || this.#physical.destroyed) return
+    this.#pumping = true
+    setImmediate(() => void this.#pump())
+  }
+
+  /** @returns {Promise<void>} */
+  async #pump() {
+    const ownerPhysical = this.#physical
+    try {
+      while (this.#authenticated && ownerPhysical !== undefined && this.#physical === ownerPhysical && !ownerPhysical.destroyed) {
+        const physical = ownerPhysical
+        const control = this.#controlQueue.shift()
+        if (control !== undefined) {
+          this.#controlQueuedBytes = Math.max(0, this.#controlQueuedBytes - control.length)
+          this.#options.aggregateBudget?.releaseControl(control.length)
+          if (!await writePhysical(physical, control)) break
+          continue
+        }
+        if (this.#resuming) break
+        const streams = [...this.#streams.values()]
+        if (streams.length === 0) break
+        let selected
+        for (let index = 0; index < streams.length; index += 1) {
+          const cursor = (this.#roundRobinCursor + index) % streams.length
+          const candidate = /** @type {ClientStream} */ (streams[cursor])
+          const frame = candidate.queue[0]
+          if (frame !== undefined && candidate.opened && (frame.type !== V3FrameType.DATA || frame.payloadBytes <= candidate.sendWindow)) {
+            selected = {stream: candidate, frame, next: (cursor + 1) % streams.length}
+            break
+          }
+        }
+        if (selected === undefined) break
+        selected.stream.queue.shift()
+        this.#roundRobinCursor = selected.next
+        if (selected.frame.type === V3FrameType.DATA) selected.stream.sendWindow -= selected.frame.payloadBytes
+        if (!await writePhysical(physical, selected.frame.wire)) break
+        await new Promise((resolve) => setImmediate(resolve))
+      }
+    } finally {
+      this.#pumping = false
+      if (this.#controlQueue.length > 0 || (!this.#resuming && [...this.#streams.values()].some((stream) => {
+        const frame = stream.queue[0]
+        return stream.opened && frame !== undefined && (frame.type !== V3FrameType.DATA || frame.payloadBytes <= stream.sendWindow)
+      }))) this.#schedulePump()
+    }
+  }
+
+  /**
+   * @param {ClientStream} stream - Stream. @param {number} sequence - Ack. @returns {void}
+   * @param sequence
+   */
+  #applyAck(stream, sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence < stream.sendAck || sequence > stream.sendSequence) throw new Error("Invalid V3 stream acknowledgement")
+    if (sequence === stream.sendAck) return
+    const oldAck = stream.sendAck
+    stream.sendAck = sequence
+    let removed = 0
+    stream.replay = stream.replay.filter((chunk) => {
+      if (chunk.sequence <= sequence) {
+        removed += chunk.data.length
+        return false
+      }
+      return true
+    })
+    stream.bufferedBytes = Math.max(0, stream.bufferedBytes - removed)
+    this.#aggregateBufferedBytes = Math.max(0, this.#aggregateBufferedBytes - removed)
+    this.#options.aggregateBudget?.releaseMemory(removed)
+    stream.sendWindow = Math.min(this.#initialWindow(), stream.sendWindow + (sequence - oldAck))
+    void this.#queueSpoolOperation(stream, async () => {
+      await this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream))
+      await this.#spool.truncateAcked(stream.identifier, sequence)
+      if (removed > stream.spoolReservedBytes) throw new Error("Socketduct stream spool budget release underflow")
+      stream.spoolReservedBytes -= removed
+      this.#aggregateSpoolBytes -= removed
+      this.#options.aggregateBudget?.releaseSpool(removed)
+    }).catch((error) => stream.socket._receiveError(asError(error)))
+    this.#schedulePump()
+  }
+
+  /**
+   * @param {ClientStream} stream - Stream. @param {number} sequence - Ack. @returns {void}
+   * @param sequence
+   */
+  #ackReceived(stream, sequence) {
+    const delta = sequence - stream.receiveAck
+    if (delta <= 0) return
+    stream.receiveAck = sequence
+    stream.receiveUnackedBytes = Math.max(0, stream.receiveUnackedBytes - delta)
+    const generation = this.#generation
+    void this.#persistStreamState(stream).then(() => {
+      if (this.#streams.get(stream.id) === stream && !stream.remoteClosed && this.#generation === generation && this.#authenticated && !this.#resuming) this.#queueControlFrame(V3FrameType.ACK, stream.id, sequence, {})
+    }, (error) => stream.socket._receiveError(asError(error)))
+  }
+
+  /** @returns {void} */
+  #completeConnection() {
+    this.#resuming = false
+    this.#reconnectAttempts = 0
+    this.#startHeartbeat()
+    this.#setPhysicalState("ready")
+    logDiagnostic(this.#options.logger, "transport.connected", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts,
+      physicalConnects: this.#physicalConnects,
+      reconnect: this.#physicalConnects > 1
+    })
+    if (this.#physicalConnects > 1) {
+      logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
+        generation: this.#generation,
+        attempt: this.#reconnectAttemptTotal,
+        physicalConnects: this.#physicalConnects
+      })
+    }
+    this.#resolveConnect?.()
+    this.#settleConnect()
+    for (const stream of this.#streams.values()) {
+      if (!stream.opened) this.#openStream(stream)
+      else stream.socket._markConnected()
+    }
+    this.#schedulePump()
+  }
+
+  /** @returns {void} */
+  #settleConnect() {
+    this.#connectPromise = undefined
+    this.#resolveConnect = undefined
+    this.#rejectConnect = undefined
+  }
+
+  /**
+   * @param {Error} error - Failure. @param {boolean} retry - Whether retryable. @returns {void}
+   * @param retry
+   */
+  #failAttempt(error, retry) {
+    if (!retry || (this.#options.continuousReconnect !== true && this.#reconnectAttempts >= (this.#options.maxReconnectAttempts ?? 8))) {
+      this.#failAll(error)
+      return
+    }
+    logDiagnostic(this.#options.logger, "transport.failed", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts,
+      ...errorDiagnostics(error)
+    })
+    this.#scheduleReconnect()
+  }
+
+  /** @returns {void} */
+  #scheduleReconnect() {
+    if (this.#closing || this.#reconnectTimer !== undefined) return
+    if (this.#options.continuousReconnect !== true && this.#reconnectAttempts >= (this.#options.maxReconnectAttempts ?? 8)) {
+      this.#failAll(new SocketductSessionLostError("Socketduct reconnect limit exceeded", "RECONNECT_EXHAUSTED"))
+      return
+    }
+    this.#setPhysicalState("reconnecting")
+    const delayMs = this.#options.reconnectDelayMs ?? 25
+    logDiagnostic(this.#options.logger, "transport.reconnect_scheduled", {
+      generation: this.#generation,
+      attempt: this.#reconnectAttemptTotal + 1,
+      delayMs
+    })
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = undefined
+      if (this.#connectPromise === undefined) {
+        this.#connectPromise = new Promise((resolve, reject) => {
+          this.#resolveConnect = resolve
+          this.#rejectConnect = reject
+        })
+        this.#connectPromise.catch(() => {})
+      }
+      this.#connectPhysical()
+    }, delayMs)
+    this.#reconnectTimer.unref?.()
+  }
+
+  /** @param {Error} error - Terminal connection failure. @returns {void} */
+  #failAll(error) {
+    logDiagnostic(this.#options.logger, "transport.failed", {
+      generation: this.#generation,
+      attempt: this.#physicalAttempts,
+      ...errorDiagnostics(error)
+    })
+    this.#closing = true
+    this.#setPhysicalState("closed", error)
+    this.#stopHeartbeat()
+    this.#clearControlQueue()
+    this.#physical?.destroy()
+    this.#rejectConnect?.(error)
+    this.#settleConnect()
+    for (const stream of [...this.#streams.values()]) stream.socket._receiveError(error)
+  }
+
+  /** @returns {number} */
+  #initialWindow() { return this.#options.initialWindowBytes ?? DEFAULT_WINDOW }
+
+  /** @returns {number} */
+  #maxFrameBytes() { return Math.min(this.#options.maxFrameBytes ?? DEFAULT_FRAME_BYTES, 64 * 1024) }
+
+  /** @returns {number} */
+  #maxStreamBytes() { return this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BYTES }
+
+  /** @returns {number} */
+  #maxConnectionBytes() { return this.#options.maxConnectionBufferBytes ?? DEFAULT_CONNECTION_BYTES }
+
+  /** @returns {void} */
+  #startHeartbeat() {
+    this.#stopHeartbeat()
+    const interval = this.#options.heartbeatIntervalMs ?? 30_000
+    const timeout = this.#options.heartbeatTimeoutMs ?? 90_000
+    this.#lastPongAt = Date.now()
+    this.#heartbeatTimer = setInterval(() => {
+      if (!this.#authenticated || this.#physical === undefined) return
+      if (Date.now() - this.#lastPongAt > timeout) {
+        this.#physical.destroy(new Error("Socketduct heartbeat timeout"))
+        return
+      }
+      this.#pingSequence += 1
+      this.#queueControlFrame(V3FrameType.PING, 0, this.#pingSequence, {})
+    }, interval)
+    this.#heartbeatTimer.unref?.()
+  }
+
+  /** @returns {void} */
+  #stopHeartbeat() {
+    if (this.#heartbeatTimer !== undefined) clearInterval(this.#heartbeatTimer)
+    this.#heartbeatTimer = undefined
+  }
+
+  /** @returns {void} */
+  #clearControlQueue() {
+    if (this.#controlQueuedBytes > 0) this.#options.aggregateBudget?.releaseControl(this.#controlQueuedBytes)
+    this.#controlQueue = []
+    this.#controlQueuedBytes = 0
+  }
+
+  /**
+   * @param {"configured" | "connecting" | "ready" | "reconnecting" | "disconnected" | "closed"} state - New lifecycle state.
+   * @param {Error} [error] - Terminal error.
+   * @returns {void}
+   */
+  #setPhysicalState(state, error) {
+    if (this.#physicalState === state) return
+    this.#physicalState = state
+    this.emit("stateChange", state, error)
+  }
+
+  /** @param {import('node:net').Socket} physical - Attempt owner. @returns {void} */
+  #clearAttemptTimeout(physical) {
+    const timer = this.#attemptTimers.get(physical)
+    if (timer !== undefined) clearTimeout(timer)
+    this.#attemptTimers.delete(physical)
+  }
+
+  /** @param {ClientStream} stream - Stream. @returns {ClientRecoveryState} */
+  #recoveryState(stream) {
+    return {
+      version: 3,
+      connectionId: this.#connectionId,
+      generation: this.#generation,
+      streamId: stream.id,
+      identifier: stream.identifier,
+      name: stream.name,
+      target: stream.target,
+      opened: stream.opened,
+      openingSent: stream.openingSent,
+      localEnded: stream.localEnded,
+      sendSequence: stream.sendSequence,
+      sendAck: stream.sendAck,
+      receiveSequence: stream.receiveSequence,
+      receiveAck: stream.receiveAck
+    }
+  }
+
+  /** @param {ClientStream} stream - Stream. @returns {Promise<void>} */
+  async #persistStreamState(stream) {
+    await this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream)))
+  }
+
+  /**
+   * @param {ClientStream} stream - Stream spool owner. @param {() => Promise<void>} operation - Serialized operation. @returns {Promise<void>}
+   * @param operation
+   */
+  async #queueSpoolOperation(stream, operation) {
+    const next = stream.spoolQueue.then(async () => {
+      await stream.spoolReady
+      await operation()
+    })
+    stream.spoolQueue = next.catch(() => {})
+    await next
+  }
+
+  /** @param {ClientStream} stream - Stream spool owner. @returns {Promise<void>} */
+  async #removeSpool(stream) {
+    if (stream.spoolRemovalPromise === undefined) {
+      stream.spoolRemovalQueued = true
+      stream.spoolRemovalPromise = this.#queueSpoolOperation(stream, async () => {
+        await this.#spool.remove(stream.identifier)
+        const removed = stream.spoolReservedBytes
+        stream.spoolReservedBytes = 0
+        this.#aggregateSpoolBytes -= removed
+        this.#options.aggregateBudget?.releaseSpool(removed)
+      })
+    }
+    await stream.spoolRemovalPromise
+  }
+
+  /** @param {ClientStream} stream - Destroyed spool owner. @returns {void} */
+  #trackSpoolCleanup(stream) {
+    const removal = stream.ownsSpool
+      ? this.#removeSpool(stream)
+      : stream.spoolReady.then(() => stream.ownsSpool ? this.#removeSpool(stream) : undefined)
+    const task = removal.catch((cleanupError) => {
+      const error = asError(cleanupError)
+      this.#handleSpoolCleanupFailure(stream, error)
+      throw error
+    })
+    this.#spoolCleanupTasks.add(task)
+    void task.catch(() => {}).finally(() => this.#spoolCleanupTasks.delete(task))
+  }
+
+  /**
+   * @param {ClientStream} stream - Failed spool owner.
+   * @param {Error} error - Durable cleanup failure.
+   * @returns {void}
+   */
+  #handleSpoolCleanupFailure(stream, error) {
+    if (stream.spoolCleanupFailureRecorded) return
+    stream.spoolCleanupFailureRecorded = true
+    this.#spoolCleanupFailures += 1
+    if (!this.#closing) {
+      const lifecycleError = new SocketductSessionLostError("Socketduct durable spool cleanup failed", "SPOOL_CLEANUP_FAILED")
+      lifecycleError.cause = error
+      this.#failAll(lifecycleError)
+    }
+  }
+}
+
+/**
+ * Constructs a reusable protocol-v3 physical connection. No network resource is
+ * allocated until its first virtual stream is opened.
+ * @param {MultiplexedConnectionOptions} options - Connection options.
+ * @returns {MultiplexedSocketductConnection} Shared transport owner.
+ */
+export function createMultiplexedSocketductConnection(options) {
+  return new MultiplexedSocketductConnection(options)
+}
+
+/** @param {MultiplexedConnectionOptions} options - Options. @returns {void} */
+function validateConnectionOptions(options) {
+  if (typeof options !== "object" || options === null || typeof options.relay?.host !== "string" || !validPort(options.relay?.port) || typeof options.relay?.token !== "string" || options.relay.token.length === 0) {
+    throw new TypeError("Multiplexed Socketduct relay host, port, and token are required")
+  }
+  if (options.connectionId !== undefined && !STABLE_IDENTIFIER.test(options.connectionId)) throw new TypeError("connectionId must be 8-128 URL-safe opaque characters")
+  if (options.continuousReconnect !== undefined && typeof options.continuousReconnect !== "boolean") throw new TypeError("continuousReconnect must be a boolean")
+  for (const [name, value] of Object.entries({
+    initialWindowBytes: options.initialWindowBytes,
+    maxFrameBytes: options.maxFrameBytes,
+    maxStreamBufferBytes: options.maxStreamBufferBytes,
+    maxConnectionBufferBytes: options.maxConnectionBufferBytes,
+    maxStreams: options.maxStreams,
+    maxReconnectAttempts: options.maxReconnectAttempts,
+    connectTimeoutMs: options.connectTimeoutMs,
+    maxAgeMs: options.maxAgeMs,
+    heartbeatIntervalMs: options.heartbeatIntervalMs,
+    heartbeatTimeoutMs: options.heartbeatTimeoutMs
+  })) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) throw new RangeError(`${name} must be a positive integer`)
+  }
+  if ((options.tls?.certFile === undefined) !== (options.tls?.keyFile === undefined)) throw new Error("TLS certFile and keyFile must both be set")
+  if ((options.heartbeatTimeoutMs ?? 90_000) <= (options.heartbeatIntervalMs ?? 30_000)) throw new RangeError("heartbeatTimeoutMs must exceed heartbeatIntervalMs")
+  if ((options.maxFrameBytes ?? DEFAULT_FRAME_BYTES) > (options.initialWindowBytes ?? DEFAULT_WINDOW)) throw new RangeError("maxFrameBytes must not exceed initialWindowBytes")
+  if ((options.initialWindowBytes ?? DEFAULT_WINDOW) > (options.maxStreamBufferBytes ?? DEFAULT_STREAM_BYTES)) throw new RangeError("initialWindowBytes must not exceed maxStreamBufferBytes")
+}
+
+/**
+ * @param {Record<string, unknown>} value - Parsed durable state.
+ * @param {{connectionId: string, identifier: string, target: {host: string, port: number}, sessionName?: string}} expected - Caller-owned identity.
+ * @returns {ClientRecoveryState} Validated recovery state.
+ */
+function validateRecoveryState(value, expected) {
+  const state = /** @type {Partial<ClientRecoveryState>} */ (value)
+  const sequences = [state.generation, state.streamId, state.sendSequence, state.sendAck, state.receiveSequence, state.receiveAck]
+  const validSequences = sequences.every((sequence) => Number.isSafeInteger(sequence) && /** @type {number} */ (sequence) >= 0)
+  const validTarget = state.target?.host === expected.target.host && state.target?.port === expected.target.port
+  if (state.version !== 3 || state.connectionId !== expected.connectionId || state.identifier !== expected.identifier || !validSequences || state.generation === 0 || state.streamId === 0 || /** @type {number} */ (state.streamId) % 2 === 0 || /** @type {number} */ (state.streamId) > 0xffff_fffd || typeof state.name !== "string" || state.name.length === 0 || state.name.length > 256 || !validTarget || typeof state.opened !== "boolean" || state.openingSent !== true || typeof state.localEnded !== "boolean" || /** @type {number} */ (state.sendAck) > /** @type {number} */ (state.sendSequence) || /** @type {number} */ (state.receiveAck) > /** @type {number} */ (state.receiveSequence) || (expected.sessionName !== undefined && state.name !== expected.sessionName)) {
+    throw new Error("Invalid Socketduct recovery identity or sequence state")
+  }
+  return /** @type {ClientRecoveryState} */ (state)
+}
+
+/**
+ * @param {ClientStream} stream - Recovered owner.
+ * @param {import('../spool/spool-file.js').SpoolChunk[]} chunks - Durable chunks after ACK.
+ * @param {number} maxBytes - Per-stream bound.
+ * @returns {void}
+ */
+function validateRecoveredChunks(stream, chunks, maxBytes) {
+  let sequence = stream.sendAck
+  let bytes = 0
+  for (const chunk of chunks) {
+    bytes += chunk.data.length
+    if (chunk.data.length === 0 || chunk.sequence !== sequence + chunk.data.length || chunk.sequence > stream.sendSequence) throw new Error("Invalid Socketduct recovery chunk sequence")
+    sequence = chunk.sequence
+  }
+  if (sequence !== stream.sendSequence || bytes > maxBytes) throw new Error("Invalid or oversized Socketduct recovery replay state")
+}
+
+/** @param {VirtualConnectionOptions} options - Options. @returns {{host: string, port: number}} */
+function normalizeTarget(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}
+}
+
+/** @param {unknown} port - Port. @returns {port is number} */
+function validPort(port) { return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65_535 }
+
+/** @param {{caFile?: string, certFile?: string, keyFile?: string, servername?: string, rejectUnauthorized?: boolean}} options - TLS files. @returns {Record<string, unknown>} */
+function resolveTls(options) {
+  return {
+    rejectUnauthorized: options.rejectUnauthorized !== false,
+    ...(options.caFile === undefined ? {} : {ca: readFileSync(options.caFile)}),
+    ...(options.certFile === undefined ? {} : {cert: readFileSync(options.certFile)}),
+    ...(options.keyFile === undefined ? {} : {key: readFileSync(options.keyFile)}),
+    ...(options.servername === undefined ? {} : {servername: options.servername})
+  }
+}
+
+/** @param {{host: string, port: number, tls?: Record<string, unknown>}} options - Transport. @returns {import('node:net').Socket} */
+function createPhysicalSocket(options) {
+  return options.tls === undefined ? netConnect({host: options.host, port: options.port}) : tlsConnect({host: options.host, port: options.port, ...options.tls})
+}
+
+/**
+ * @param {import('node:net').Socket} socket - Physical socket. @param {Buffer} bytes - Frame. @returns {Promise<boolean>}
+ * @param bytes
+ */
+async function writePhysical(socket, bytes) {
+  if (socket.destroyed || !socket.writable) return false
+  if (socket.write(bytes)) return true
+  return await new Promise((resolve) => {
+    const cleanup = () => {
+      socket.off("drain", onDrain)
+      socket.off("close", onClose)
+    }
+    const onDrain = () => { cleanup(); resolve(true) }
+    const onClose = () => { cleanup(); resolve(false) }
+    socket.once("drain", onDrain)
+    socket.once("close", onClose)
+  })
+}
+
+/**
+ * @param {VirtualSocket} socket - Socket. @param {(error: Error | null, socket: VirtualSocket) => void} callback - Callback. @returns {void}
+ * @param callback
+ */
+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 - Pre-connect error. */
+  const onError = (error) => {
+    if (settled) return
+    settled = true
+    cleanup()
+    callback(error, socket)
+  }
+  socket.once("connect", onConnect)
+  socket.once("error", onError)
+}
+
+/** @param {unknown} value - Thrown value. @returns {Error} */
+function asError(value) { return value instanceof Error ? value : new Error(String(value)) }
+
+/** @param {Error} error - Transport error. @returns {boolean} */
+function isFatalTransportError(error) {
+  const code = /** @type {{code?: unknown}} */ (error).code
+  return typeof code === "string" && (code.startsWith("ERR_TLS_") || code.startsWith("ERR_SSL_") || code.includes("CERT"))
+}