socketduct 0.1.20 → 0.1.21

package/src/client/virtual-socket.js

@@ -7,7 +7,10 @@ import {Duplex} from "node:stream"
  * @property {(streamId: number, callback: (error?: Error | null) => void) => void} _endStream - End the writable side.
  * @property {(streamId: number, error: Error | null) => void} _destroyStream - Destroy the virtual stream.
  * @property {(streamId: number) => void} _resumeReadable - Resume inbound flow.
+ * @property {(streamId: number, data: Buffer, callback: (error?: Error | null) => void) => void} [_writeDurableStream] - Atomically admit one durable application operation.
+ * @property {(streamId: number, bytes: number) => void} [_deliverReadable] - Report bytes exposed to the application.
  * @property {(streamId: number, bytes: number) => void} [_consumeReadable] - Report bytes returned to the application.
+ * @property {(streamId: number, bytes: number) => Promise<number>} [_acknowledgeReadable] - Durably acknowledge application bytes.
  * @property {() => {address?: string, port?: number}} physicalAddress - Current physical endpoint.
  * @property {() => unknown} ref - Reference owner resources.
  * @property {() => unknown} unref - Unreference owner resources.
@@ -74,6 +77,18 @@ export class VirtualSocket extends Duplex {
   /** @type {number} */
   #emittedDataBytes = 0
 
+  /** @type {boolean} */
+  #manualReceiveAck
+
+  /** @type {number} */
+  #deliveredReadableBytes = 0
+
+  /** @type {number} */
+  #requestedReceiveAckBytes = 0
+
+  /** @type {WeakMap<Buffer, {resolve: () => void, reject: (error: Error) => void}>} */
+  #durableWrites = new WeakMap()
+
   /** @type {boolean} */
   connecting = true
 
@@ -104,7 +119,7 @@ export class VirtualSocket extends Duplex {
   /**
    * @param {VirtualSocketOwner} connection - Owner.
    * @param {number} streamId - Allocated stream ID.
-   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} options - Socket metadata/options.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number, manualReceiveAck?: boolean}} options - Socket metadata/options.
    */
   constructor(connection, streamId, options) {
     super({
@@ -114,6 +129,7 @@ export class VirtualSocket extends Duplex {
     })
     this.#connection = connection
     this.#streamId = streamId
+    this.#manualReceiveAck = options.manualReceiveAck ?? false
     this.remoteAddress = options.host
     this.remotePort = options.port
     this.remoteFamily = options.host.includes(":") ? "IPv6" : "IPv4"
@@ -124,6 +140,11 @@ export class VirtualSocket extends Duplex {
     return this.#streamId
   }
 
+  /** @returns {boolean} Whether application-controlled receive ACK is enabled. */
+  get manualReceiveAck() {
+    return this.#manualReceiveAck
+  }
+
   /** @returns {this} Socket-style no-op connect; opening starts at construction. */
   connect() {
     return this
@@ -151,7 +172,11 @@ export class VirtualSocket extends Duplex {
     if (chunk !== null) {
       const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
       const emittedBytes = this.#emittedDataBytes - emittedBefore
-      if (bytes > emittedBytes) this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+      if (bytes > emittedBytes) {
+        this.#deliveredReadableBytes += bytes - emittedBytes
+        this.#connection._deliverReadable?.(this.#streamId, bytes - emittedBytes)
+        this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+      }
     }
     return chunk
   }
@@ -165,14 +190,57 @@ export class VirtualSocket extends Duplex {
    * @override
    */
   emit(event, ...args) {
-    const emitted = super.emit(event, ...args)
     const chunk = args[0]
     if (event === "data" && (typeof chunk === "string" || Buffer.isBuffer(chunk))) {
       const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
       this.#emittedDataBytes += bytes
+      this.#deliveredReadableBytes += bytes
+      this.#connection._deliverReadable?.(this.#streamId, bytes)
+      const emitted = super.emit(event, ...args)
       this.#connection._consumeReadable?.(this.#streamId, bytes)
+      return emitted
     }
-    return emitted
+    return super.emit(event, ...args)
+  }
+
+  /**
+   * Durably admits one complete application operation before any of its bytes
+   * become eligible for transmission.
+   * @param {string | ArrayBufferView} chunk - Complete serialized operation.
+   * @param {BufferEncoding} [encoding] - String encoding.
+   * @returns {Promise<void>} Resolves after all bytes and recovery metadata are committed.
+   */
+  writeDurable(chunk, encoding = "utf8") {
+    if (this.destroyed) return Promise.reject(contractError("Socketduct stream is destroyed", "ERR_STREAM_DESTROYED"))
+    if (this.writableEnded || this.writableFinished) return Promise.reject(contractError("Socketduct stream has ended", "ERR_STREAM_WRITE_AFTER_END"))
+    if (this.#connection._writeDurableStream === undefined) return Promise.reject(contractError("Durable write admission is unavailable for this Socketduct transport", "SOCKETDUCT_DURABLE_WRITE_UNSUPPORTED"))
+    const data = bufferFromView(chunk, encoding)
+    this.#resetTimeout()
+    return new Promise((resolve, reject) => {
+      this.#durableWrites.set(data, {resolve, reject})
+      this.write(data, (error) => {
+        if (error !== undefined && error !== null) reject(error)
+      })
+    })
+  }
+
+  /**
+   * Advances the durable receive ACK by application bytes after parser/journal
+   * state is durable.
+   * @param {number} bytes - Newly durable application bytes.
+   * @returns {Promise<number>} New cumulative durable receive sequence.
+   */
+  acknowledgeReceive(bytes) {
+    if (!this.#manualReceiveAck) throw contractError("Manual receive acknowledgement is not enabled for this socket", "SOCKETDUCT_MANUAL_ACK_DISABLED")
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) throw contractError("Receive acknowledgement bytes must be a positive safe integer", "SOCKETDUCT_INVALID_RECEIVE_ACK")
+    if (this.destroyed) return Promise.reject(contractError("Socketduct stream is destroyed", "ERR_STREAM_DESTROYED"))
+    if (this.#requestedReceiveAckBytes + bytes > this.#deliveredReadableBytes) throw contractError("Receive acknowledgement exceeds bytes delivered to the application", "SOCKETDUCT_INVALID_RECEIVE_ACK")
+    if (this.#connection._acknowledgeReadable === undefined) return Promise.reject(contractError("Manual receive acknowledgement is unavailable for this Socketduct transport", "SOCKETDUCT_MANUAL_ACK_UNSUPPORTED"))
+    this.#requestedReceiveAckBytes += bytes
+    return this.#connection._acknowledgeReadable(this.#streamId, bytes).catch((error) => {
+      this.#requestedReceiveAckBytes -= bytes
+      throw error
+    })
   }
 
   /**
@@ -183,6 +251,24 @@ export class VirtualSocket extends Duplex {
    * @returns {void}
    */
   _write(chunk, encoding, callback) {
+    const durableChunk = Buffer.isBuffer(chunk) ? /** @type {Buffer} */ (chunk) : undefined
+    const durable = durableChunk === undefined ? undefined : this.#durableWrites.get(durableChunk)
+    if (durable !== undefined) {
+      const data = /** @type {Buffer} */ (durableChunk)
+      this.#durableWrites.delete(data)
+      this.#resetTimeout()
+      this.#connection._writeDurableStream?.(this.#streamId, data, (error) => {
+        if (error !== undefined && error !== null) durable.reject(error)
+        else {
+          this.bytesWritten += data.length
+          durable.resolve()
+        }
+        // Admission failures reject writeDurable() but remain retryable, so the
+        // Writable queue advances without turning the whole socket terminal.
+        callback()
+      })
+      return
+    }
     const data = typeof chunk === "string" ? Buffer.from(chunk, encoding) : Buffer.from(chunk)
     this.#resetTimeout()
     this.#connection._writeStream(this.#streamId, data, (error) => {
@@ -306,3 +392,22 @@ export class VirtualSocket extends Duplex {
     this.#timeoutTimer.unref?.()
   }
 }
+
+/**
+ * @param {string} message - Safe message.
+ * @param {string} code - Stable code.
+ */
+function contractError(message, code) {
+  return new SocketductStreamError(message, code)
+}
+
+/**
+ * @param {string | ArrayBufferView} value - Bytes.
+ * @param {BufferEncoding} encoding - String encoding.
+ * @returns {Buffer} Owned bytes.
+ */
+function bufferFromView(value, encoding) {
+  if (typeof value === "string") return Buffer.from(value, encoding)
+  if (!ArrayBuffer.isView(value)) throw new TypeError("Durable write requires a string, TypedArray, or DataView")
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+}

package/src/index.js

@@ -9,7 +9,7 @@ export {createCompressedJsonlFileLogger, CompressedJsonlFileLogger} from "./logg
 export {SocketductHttpAgent} from "./client/http-agent.js"
 export {connectSocketduct, SocketductRelayError, SocketductSocket} from "./client/socketduct-socket.js"
 export {createMultiplexedSocketductConnection, MultiplexedSocketductConnection} from "./client/multiplexed-connection.js"
-export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./client/multiplexed-transport-set.js"
+export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductRecoveryLookupError, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./client/multiplexed-transport-set.js"
 export {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "./client/virtual-socket.js"
 export {createOutboundReverseGateway, createReverseGatewayConnection, OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "./reverse/index.js"
 

package/src/reverse/client.js

@@ -63,6 +63,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @typedef {object} PendingClientWrite
  * @property {Buffer} data
  * @property {number} offset
+ * @property {boolean} durable
  * @property {(error?: Error | null) => void} callback
  * @typedef {object} ReverseClientStream
  * @property {number} id
@@ -80,6 +81,9 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {number} sendWindowLimit
  * @property {number} receiveSequence
  * @property {number} receiveAck
+ * @property {number} receiveDelivered
+ * @property {number} pendingReceiveAckBytes
+ * @property {boolean} manualReceiveAck
  * @property {Array<{sequence: number, remaining: number}>} receiveFrames
  * @property {boolean} remoteEnded
  * @property {boolean} remoteEndPending
@@ -87,8 +91,9 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {ClientChunk[]} replay
  * @property {AdaptiveCompressor} compressor
  * @property {boolean} pumping
- * @property {PendingClientWrite | undefined} pendingWrite
+ * @property {PendingClientWrite[]} pendingWrites
  * @property {boolean} progressingWrite
+ * @property {Promise<void> | undefined} writeTask
  * @property {boolean} localEnded
  * @property {boolean} endSent
  * @property {((error?: Error | null) => void) | undefined} endCallback
@@ -99,6 +104,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {boolean} spoolCleanupFailureRecorded
  * @property {boolean} ownsSpool
  * @property {boolean} recoveredObject
+ * @property {Promise<number>} manualAckQueue
  * @typedef {object} ReverseClientRecoveryState
  * @property {number} version
  * @property {'reverse-client'} role
@@ -120,6 +126,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {boolean} localEnded
  * @property {boolean} remoteEnded
  * @property {boolean} endSent
+ * @property {boolean} [manualReceiveAck]
  */
 
 /** Server3/TensorBuzz-facing virtual socket connection to an exact gateway or server-resolved route class. */
@@ -133,6 +140,7 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #generation
   /** @type {string | undefined} */ #codec
   /** @type {boolean} */ #closing = false
+  /** @type {boolean} */ #detached = false
   /** @type {boolean} */ #preserveSpools = false
   /** @type {boolean} */ #fatal = false
   /** @type {Error | undefined} */ #fatalError
@@ -206,9 +214,31 @@ export class ReverseGatewayConnection extends EventEmitter {
     return this.#createConnection(options, callback, true)
   }
 
+  /**
+   * Reads and validates one durable descriptor without allocating a socket.
+   * @param {string} identifier - Stable stream identifier.
+   * @returns {{identifier: string, target: {host: string, port: number}, sessionName: string, manualReceiveAck: boolean} | undefined} Recovery descriptor.
+   */
+  _inspectRecoveredConnection(identifier) {
+    if (typeof identifier !== "string" || !STABLE_IDENTIFIER.test(identifier)) throw new TypeError("Reverse virtual stream identifier must be 8-128 URL-safe characters")
+    const value = this.#spool.findRecoveryStateSync(identifier, "reverse-client-v3")
+    if (value === undefined) return undefined
+    const target = parseTarget(/** @type {{host?: unknown, port?: unknown}} */ (value.target))
+    if (target === undefined) throw new Error("Invalid reverse client recovery target")
+    const state = validateRecoveryState(value, {
+      connectionId: this.#connectionId,
+      identifier,
+      target,
+      selection: this.#routeIdentityFields(),
+      initialWindow: this.#initialWindow()
+    })
+    return {identifier, target, sessionName: state.name, manualReceiveAck: state.manualReceiveAck === true}
+  }
+
   /** Creates a fresh or synchronously recovered reverse stream. */
   #createConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback, /** @type {boolean} */ recovering) {
     if (this.#closing) throw closedError()
+    if (options?.manualReceiveAck !== undefined && typeof options.manualReceiveAck !== "boolean") throw new TypeError("manualReceiveAck must be a boolean")
     if (!recovering && this.#state !== "ready") throw Object.assign(new Error("Reverse gateway member is not ready"), {code: "SOCKETDUCT_TRANSPORT_SET_NOT_READY"})
     if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum reverse virtual stream count exceeded")
     const target = parseTarget(options?.target ?? {host: options?.host, port: options?.port})
@@ -222,7 +252,8 @@ export class ReverseGatewayConnection extends EventEmitter {
         target,
         selection: this.#routeIdentityFields(),
         initialWindow: this.#initialWindow(),
-        ...(options.sessionName === undefined ? {} : {sessionName: options.sessionName})
+        ...(options.sessionName === undefined ? {} : {sessionName: options.sessionName}),
+        ...(options.manualReceiveAck === undefined ? {} : {manualReceiveAck: options.manualReceiveAck})
       })
       : undefined
     const chunks = recovery === undefined ? [] : this.#spool.loadChunksSync(identifier, "reverse-client-v3", recovery.sendAck, recovery.sendSequence)
@@ -233,11 +264,13 @@ export class ReverseGatewayConnection extends EventEmitter {
     if (this.#streams.has(id)) throw new Error(`Reverse v3 stream ID ${id} is already active`)
     const name = options.sessionName ?? recovery?.name ?? `socketduct-reverse-${id}`
     if (typeof name !== "string" || name.length === 0 || name.length > 256) throw new TypeError("Reverse virtual stream name must be 1-256 characters")
+    const manualReceiveAck = recovery?.manualReceiveAck ?? options.manualReceiveAck ?? false
     const socket = new VirtualSocket(/** @type {import('../client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ (this)), id, {
       ...target,
       ...(options.allowHalfOpen === undefined ? {} : {allowHalfOpen: options.allowHalfOpen}),
       ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
-      ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+      ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark}),
+      manualReceiveAck
     })
     /** @type {ReverseClientStream} */
     const stream = {
@@ -254,6 +287,9 @@ export class ReverseGatewayConnection extends EventEmitter {
       // delivered. Resume inbound delivery from the persisted ACK boundary.
       receiveSequence: recovery?.receiveAck ?? 0,
       receiveAck: recovery?.receiveAck ?? 0,
+      receiveDelivered: recovery?.receiveAck ?? 0,
+      pendingReceiveAckBytes: 0,
+      manualReceiveAck,
       receiveFrames: [],
       remoteEnded: recovery?.remoteEnded ?? false,
       remoteEndPending: recovery?.remoteEnded ?? false,
@@ -261,8 +297,9 @@ export class ReverseGatewayConnection extends EventEmitter {
       replay: chunks.map((chunk) => ({...chunk, sent: false})),
       compressor: new AdaptiveCompressor(),
       pumping: false,
-      pendingWrite: undefined,
+      pendingWrites: [],
       progressingWrite: false,
+      writeTask: undefined,
       localEnded: recovery?.localEnded ?? false,
       endSent: recovery?.endSent ?? false,
       endCallback: undefined,
@@ -272,7 +309,8 @@ export class ReverseGatewayConnection extends EventEmitter {
       spoolRemovalPromise: undefined,
       spoolCleanupFailureRecorded: false,
       ownsSpool: recovery !== undefined,
-      recoveredObject: recovery !== undefined
+      recoveredObject: recovery !== undefined,
+      manualAckQueue: Promise.resolve(recovery?.receiveAck ?? 0)
     }
     if (recovery !== undefined) {
       this.#options.aggregateBudget?.reserveData(bufferedBytes)
@@ -369,6 +407,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     if (this.#options.connectionId === undefined) throw new Error("detach() requires an explicit stable connectionId")
     if (this.#options.spoolDirectory === undefined) throw new Error("detach() requires an explicit persistent spoolDirectory")
     this.#preserveSpools = true
+    this.#detached = true
     this.#closing = true
     if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
     this.#reconnectTimer = undefined
@@ -379,7 +418,12 @@ export class ReverseGatewayConnection extends EventEmitter {
     const frameQueue = this.#physicalFrameQueue
     try {
       await frameQueue
-      await Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream)))
+      const streams = [...this.#streams.values()]
+      await Promise.all(streams.map((stream) => stream.writeTask))
+      await Promise.all(streams.map((stream) => stream.manualAckQueue))
+      const detached = new SocketductSessionLostError("Reverse connection detached before queued write admission", "SOCKETDUCT_CONNECTION_DETACHED")
+      for (const stream of streams) while (stream.pendingWrites.length > 0) this.#finishWrite(stream, detached)
+      await Promise.all(streams.filter((stream) => this.#streams.get(stream.id) === stream).map((stream) => this.#persistStreamState(stream)))
     } finally {
       physical?.destroy()
       this.#physical = undefined
@@ -391,7 +435,15 @@ export class ReverseGatewayConnection extends EventEmitter {
   _writeStream(/** @type {number} */ streamId, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) {
     const stream = this.#streams.get(streamId)
     if (this.#closing || stream === undefined || stream.localEnded || stream.state === "closed" || stream.state === "reset") { callback(new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")); return }
-    stream.pendingWrite = {data, offset: 0, callback}
+    stream.pendingWrites.push({data, offset: 0, durable: false, callback})
+    this.#progressPendingWrites()
+  }
+
+  _writeDurableStream(/** @type {number} */ streamId, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) {
+    const stream = this.#streams.get(streamId)
+    if (this.#detached) { callback(new SocketductSessionLostError("Reverse connection is detached", "SOCKETDUCT_CONNECTION_DETACHED")); return }
+    if (this.#closing || stream === undefined || stream.localEnded || stream.state === "closed" || stream.state === "reset") { callback(new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")); return }
+    stream.pendingWrites.push({data, offset: 0, durable: true, callback})
     this.#progressPendingWrites()
   }
 
@@ -424,9 +476,17 @@ export class ReverseGatewayConnection extends EventEmitter {
     void streamId
   }
 
+  _deliverReadable(/** @type {number} */ streamId, /** @type {number} */ bytes) {
+    const stream = this.#streams.get(streamId)
+    if (stream === undefined || !stream.manualReceiveAck || !Number.isSafeInteger(bytes) || bytes <= 0) return
+    stream.receiveDelivered += bytes
+    if (stream.receiveDelivered > stream.receiveSequence) throw new Error("Reverse client readable delivery accounting overflow")
+  }
+
   _consumeReadable(/** @type {number} */ streamId, /** @type {number} */ bytes) {
     const stream = this.#streams.get(streamId)
     if (stream === undefined || !Number.isSafeInteger(bytes) || bytes <= 0) return
+    if (stream.manualReceiveAck) return
     let remaining = bytes
     let acknowledgedSequence = stream.receiveAck
     while (remaining > 0 && stream.receiveFrames.length > 0) {
@@ -443,6 +503,27 @@ export class ReverseGatewayConnection extends EventEmitter {
     this.#ackReceived(stream, acknowledgedSequence)
   }
 
+  _acknowledgeReadable(/** @type {number} */ streamId, /** @type {number} */ bytes) {
+    const stream = this.#streams.get(streamId)
+    if (this.#detached) return Promise.reject(new SocketductStreamError("Reverse connection is detached", "SOCKETDUCT_CONNECTION_DETACHED"))
+    if (this.#closing) return Promise.reject(closedError())
+    if (stream === undefined) return Promise.reject(new SocketductStreamError("Reverse stream is destroyed", "ERR_STREAM_DESTROYED"))
+    if (!stream.manualReceiveAck) return Promise.reject(new SocketductStreamError("Manual receive acknowledgement is not enabled", "SOCKETDUCT_MANUAL_ACK_DISABLED"))
+    if (stream.receiveAck + stream.pendingReceiveAckBytes + bytes > stream.receiveDelivered) throw new SocketductStreamError("Receive acknowledgement exceeds bytes delivered to the application", "SOCKETDUCT_INVALID_RECEIVE_ACK")
+    stream.pendingReceiveAckBytes += bytes
+    const acknowledged = stream.manualAckQueue.then(async () => {
+      const sequence = stream.receiveAck + bytes
+      await this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream, {receiveAck: sequence})))
+      stream.receiveAck = sequence
+      stream.pendingReceiveAckBytes -= bytes
+      await this.#sendControl(V3FrameType.ACK, stream.id, sequence, {}).catch(() => {})
+      return sequence
+    })
+    stream.manualAckQueue = acknowledged
+    void acknowledged.catch((error) => stream.socket._receiveError(asError(error)))
+    return acknowledged
+  }
+
   #allocateStreamId() {
     const id = this.#nextStreamId
     if (id > 0xffff_fffd) throw new Error("Reverse v3 stream ID space exhausted")
@@ -686,7 +767,7 @@ export class ReverseGatewayConnection extends EventEmitter {
       if (this.#closing || this.#physical !== physical) return
       if (data.length === 0 || data.length > this.#maxFrameBytes() || frame.sequence !== stream.receiveSequence + data.length || frame.sequence - stream.receiveAck > this.#initialWindow()) throw new Error("Invalid reverse client DATA sequence or window")
       stream.receiveSequence = frame.sequence
-      stream.receiveFrames.push({sequence: frame.sequence, remaining: data.length})
+      if (!stream.manualReceiveAck) stream.receiveFrames.push({sequence: frame.sequence, remaining: data.length})
       stream.socket._receive(data)
       return
     }
@@ -859,10 +940,18 @@ export class ReverseGatewayConnection extends EventEmitter {
 
   /** @param {ReverseClientStream} stream - Stream with an active application write. */
   async #progressWrite(stream) {
-    const pending = stream.pendingWrite
+    const pending = stream.pendingWrites[0]
     if (pending === undefined || stream.progressingWrite || stream.state === "opening") return
     stream.progressingWrite = true
     try {
+      if (pending.durable) {
+        await this.#admitDurableWrite(stream, pending)
+        if (stream.pendingWrites[0] === pending) this.#finishWrite(stream)
+        queueMicrotask(() => {
+          void this.#pumpStream(stream).catch((error) => stream.socket._receiveError(asError(error)))
+        })
+        return
+      }
       if (pending.offset < pending.data.length && this.#streams.get(stream.id) === stream) {
         const available = this.#writeCapacity(stream)
         if (available <= 0) return
@@ -886,17 +975,65 @@ export class ReverseGatewayConnection extends EventEmitter {
         })
       }
       await this.#pumpStream(stream)
-      if (pending.offset === pending.data.length && stream.pendingWrite === pending) this.#finishWrite(stream)
+      if (pending.offset === pending.data.length && stream.pendingWrites[0] === pending) this.#finishWrite(stream)
     } catch (error) {
       const failure = asError(error)
       this.#finishWrite(stream, failure)
-      stream.socket._receiveError(failure)
+      if (!pending.durable) stream.socket._receiveError(failure)
     } finally {
       stream.progressingWrite = false
       this.#progressPendingWrites()
     }
   }
 
+  /** @param {ReverseClientStream} stream - Stream. @param {PendingClientWrite} pending - Complete durable operation. */
+  async #admitDurableWrite(stream, pending) {
+    const bytes = pending.data.length
+    if (bytes === 0) return
+    const streamCapacity = (this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES) - stream.bufferedBytes
+    const connectionCapacity = (this.#options.maxConnectionBufferBytes ?? DEFAULT_CONNECTION_BUFFER_BYTES) - this.#bufferedBytes
+    if (bytes > streamCapacity || bytes > connectionCapacity || !Number.isSafeInteger(stream.sendSequence + bytes)) throw new SocketductStreamError("Complete durable write exceeds available retained-byte capacity", "SOCKETDUCT_DURABLE_WRITE_LIMIT")
+    let reserved = false
+    try {
+      this.#options.aggregateBudget?.reserveData(bytes)
+      reserved = true
+      let sequence = stream.sendSequence
+      /** @type {ClientChunk[]} */
+      const chunks = []
+      for (let offset = 0; offset < bytes; offset += this.#maxFrameBytes()) {
+        const data = Buffer.from(pending.data.subarray(offset, Math.min(bytes, offset + this.#maxFrameBytes())))
+        sequence += data.length
+        chunks.push({sequence, data, sent: false})
+      }
+      await this.#queueSpoolOperation(stream, () => this.#spool.appendChunksAndRecoveryState({
+        sessionId: stream.identifier,
+        ownerId: "reverse-client-v3",
+        previousSequence: stream.sendSequence,
+        chunks,
+        recoveryState: this.#recoveryState(stream, {sendSequence: sequence})
+      }))
+      if (this.#streams.get(stream.id) !== stream) throw new SocketductStreamError("Reverse stream was destroyed during durable admission", "ERR_STREAM_DESTROYED")
+      stream.sendSequence = sequence
+      stream.replay.push(...chunks)
+      stream.bufferedBytes += bytes
+      this.#bufferedBytes += bytes
+      stream.spoolReservedBytes += bytes
+      this.#spoolBytes += bytes
+      pending.offset = bytes
+    } catch (error) {
+      if (reserved) {
+        this.#options.aggregateBudget?.releaseMemory(bytes)
+        this.#options.aggregateBudget?.releaseSpool(bytes)
+      }
+      const failure = asError(error)
+      const code = /** @type {{code?: unknown}} */ (failure).code
+      if (failure instanceof SocketductStreamError || (typeof code === "string" && code.startsWith("SOCKETDUCT_SET_"))) throw failure
+      const wrapped = new SocketductStreamError("Durable write persistence failed before admission", "SOCKETDUCT_DURABLE_WRITE_PERSISTENCE")
+      wrapped.cause = failure
+      throw wrapped
+    }
+  }
+
   /** @param {ReverseClientStream} stream - Stream. @returns {number} Retained-byte headroom for its next frame. */
   #writeCapacity(stream) {
     return Math.max(0, Math.min(
@@ -909,25 +1046,27 @@ export class ReverseGatewayConnection extends EventEmitter {
 
   /** Starts one bounded pending-write slice using rotating stream priority. */
   #progressPendingWrites() {
+    if (this.#closing) return
     const streams = [...this.#streams.values()]
     if (streams.length === 0) return
     const previousIndex = streams.findIndex((stream) => stream.id === this.#lastProgressedStreamId)
     const startIndex = previousIndex === -1 ? 0 : (previousIndex + 1) % streams.length
     for (let offset = 0; offset < streams.length; offset += 1) {
       const stream = /** @type {ReverseClientStream} */ (streams[(startIndex + offset) % streams.length])
-      const pending = stream.pendingWrite
-      if (pending === undefined || stream.progressingWrite || stream.state === "opening" || (pending.offset < pending.data.length && this.#writeCapacity(stream) <= 0)) continue
+      const pending = stream.pendingWrites[0]
+      if (pending === undefined || stream.progressingWrite || stream.state === "opening" || (!pending.durable && pending.offset < pending.data.length && this.#writeCapacity(stream) <= 0)) continue
       this.#lastProgressedStreamId = stream.id
-      void this.#progressWrite(stream)
+      const task = this.#progressWrite(stream)
+      stream.writeTask = task
+      void task.finally(() => { if (stream.writeTask === task) stream.writeTask = undefined })
       return
     }
   }
 
   /** @param {ReverseClientStream} stream - Stream. @param {Error} [error] - Write failure. */
   #finishWrite(stream, error) {
-    const pending = stream.pendingWrite
+    const pending = stream.pendingWrites.shift()
     if (pending === undefined) return
-    stream.pendingWrite = undefined
     pending.callback(error)
   }
 
@@ -945,7 +1084,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     this.#options.aggregateBudget?.releaseMemory(stream.bufferedBytes)
     stream.replay = []
     stream.bufferedBytes = 0
-    this.#finishWrite(stream, pendingWriteError)
+    while (stream.pendingWrites.length > 0) this.#finishWrite(stream, pendingWriteError)
     if (!this.#preserveSpools) this.#trackSpoolCleanup(stream)
     this.#progressPendingWrites()
   }
@@ -957,7 +1096,16 @@ export class ReverseGatewayConnection extends EventEmitter {
     const delta = sequence - stream.sendAck
     stream.sendAck = sequence
     let released = 0
-    stream.replay = stream.replay.filter((chunk) => { if (chunk.sequence <= sequence) { released += chunk.data.length; return false } return true })
+    stream.replay = stream.replay.flatMap((chunk) => {
+      const start = chunk.sequence - chunk.data.length
+      if (chunk.sequence <= sequence) { released += chunk.data.length; return [] }
+      if (start < sequence) {
+        const acknowledgedBytes = sequence - start
+        released += acknowledgedBytes
+        return [{...chunk, data: Buffer.from(chunk.data.subarray(acknowledgedBytes))}]
+      }
+      return [chunk]
+    })
     stream.bufferedBytes = Math.max(0, stream.bufferedBytes - released)
     this.#bufferedBytes = Math.max(0, this.#bufferedBytes - released)
     this.#options.aggregateBudget?.releaseMemory(released)
@@ -1037,8 +1185,8 @@ export class ReverseGatewayConnection extends EventEmitter {
     }
   }
 
-  /** @param {ReverseClientStream} stream - Durable stream state. */
-  #recoveryState(stream) {
+  /** @param {ReverseClientStream} stream - Durable stream state. @param {{sendSequence?: number, receiveAck?: number}} [overrides] - Commit-boundary overrides. */
+  #recoveryState(stream, overrides = {}) {
     return {
       version: 3,
       role: "reverse-client",
@@ -1052,10 +1200,11 @@ export class ReverseGatewayConnection extends EventEmitter {
       state: stream.state,
       opened: stream.opened,
       openingSent: stream.openingSent,
-      sendSequence: stream.sendSequence,
+      sendSequence: overrides.sendSequence ?? stream.sendSequence,
       sendAck: stream.sendAck,
       receiveSequence: stream.receiveSequence,
-      receiveAck: stream.receiveAck,
+      receiveAck: overrides.receiveAck ?? stream.receiveAck,
+      manualReceiveAck: stream.manualReceiveAck,
       localEnded: stream.localEnded,
       remoteEnded: stream.remoteEnded,
       endSent: stream.endSent
@@ -1145,7 +1294,7 @@ function validateOptions(options) {
 
 /**
  * @param {Record<string, unknown>} value - Parsed durable state.
- * @param {{connectionId: string, identifier: string, target: {host: string, port: number}, selection: {gatewayId: string} | {routeClass: string}, initialWindow: number, sessionName?: string}} expected - Caller-owned recovery identity.
+ * @param {{connectionId: string, identifier: string, target: {host: string, port: number}, selection: {gatewayId: string} | {routeClass: string}, initialWindow: number, sessionName?: string, manualReceiveAck?: boolean}} expected - Caller-owned recovery identity.
  * @returns {ReverseClientRecoveryState} Validated state.
  */
 function validateRecoveryState(value, expected) {
@@ -1178,6 +1327,7 @@ function validateRecoveryState(value, expected) {
     || typeof state.localEnded !== "boolean"
     || typeof state.remoteEnded !== "boolean"
     || typeof state.endSent !== "boolean"
+    || (state.manualReceiveAck !== undefined && typeof state.manualReceiveAck !== "boolean")
     || (state.endSent && !state.localEnded)
     || (state.endSent && state.opened !== true)
     || (state.remoteEnded && state.opened !== true)
@@ -1187,6 +1337,7 @@ function validateRecoveryState(value, expected) {
     || /** @type {number} */ (state.receiveAck) > /** @type {number} */ (state.receiveSequence)
     || /** @type {number} */ (state.receiveSequence) - /** @type {number} */ (state.receiveAck) > expected.initialWindow
     || (expected.sessionName !== undefined && state.name !== expected.sessionName)
+    || (expected.manualReceiveAck !== undefined && (state.manualReceiveAck === true) !== expected.manualReceiveAck)
   ) throw new Error("Invalid reverse client recovery identity, selector, lifecycle, or sequence state")
   return /** @type {ReverseClientRecoveryState} */ (state)
 }

package/src/reverse/gateway.js

@@ -735,7 +735,16 @@ export class OutboundReverseGateway extends EventEmitter {
     const delta = sequence - stream.sendAck
     stream.sendAck = sequence
     let released = 0
-    stream.replay = stream.replay.filter((chunk) => { if (chunk.sequence <= sequence) { released += chunk.data.length; return false } return true })
+    stream.replay = stream.replay.flatMap((chunk) => {
+      const start = chunk.sequence - chunk.data.length
+      if (chunk.sequence <= sequence) { released += chunk.data.length; return [] }
+      if (start < sequence) {
+        const acknowledgedBytes = sequence - start
+        released += acknowledgedBytes
+        return [{...chunk, data: Buffer.from(chunk.data.subarray(acknowledgedBytes))}]
+      }
+      return [chunk]
+    })
     stream.bufferedBytes = Math.max(0, stream.bufferedBytes - released)
     this.#bufferedBytes = Math.max(0, this.#bufferedBytes - released)
     stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + delta)