socketduct 0.1.20 → 0.1.21

package/src/spool/spool-file.js

@@ -18,6 +18,12 @@ import {join, resolve} from "node:path"
  * @property {string} [ownerId] - ownerId value.
  * @property {number} sequence - sequence value.
  * @property {Uint8Array} data - data value.
+ * @typedef {object} AppendChunkBatchInput
+ * @property {string} sessionId - Stable session identifier.
+ * @property {string} ownerId - Expected spool owner.
+ * @property {number} previousSequence - Last sequence committed by recovery metadata.
+ * @property {readonly SpoolChunk[]} chunks - Complete application operation split into frames.
+ * @property {Record<string, unknown>} recoveryState - Recovery commit written after every chunk.
  * @typedef {object} CreateSpoolInput
  * @property {string} sessionId - sessionId value.
  * @property {string} ownerId - ownerId value.
@@ -125,6 +131,23 @@ export class SessionSpool {
     }
   }
 
+  /**
+   * Looks up recovery state without treating an absent session as corruption.
+   * @param {string} sessionId - Stable session identifier.
+   * @param {string} ownerId - Expected spool owner.
+   * @returns {Record<string, unknown> | undefined} Parsed state, or undefined when the session directory is absent.
+   */
+  findRecoveryStateSync(sessionId, ownerId) {
+    const directory = this.#sessionDirectory(sessionId)
+    try {
+      statSync(directory)
+    } catch (error) {
+      if (/** @type {{code?: unknown}} */ (error).code === "ENOENT") return undefined
+      throw error
+    }
+    return this.readRecoveryStateSync(sessionId, ownerId)
+  }
+
   /**
    * Loads durable chunks synchronously so recovery can fail before network
    * activity. Ownership, age, encoding, accounting, and configured byte bounds
@@ -180,13 +203,15 @@ export class SessionSpool {
         if (usage.totalBytes !== totalBytes) throw new Error("recovery chunk accounting mismatch")
         this.#usedBytes.set(sessionId, totalBytes)
         this.#usageLoaded.add(sessionId)
-        return chunks.filter((chunk) => chunk.sequence > acknowledgedSequence)
+        return chunksAfterSequence(chunks, acknowledgedSequence)
       }
-      if (!committedChunksAreCovered(chunks, acknowledgedSequence, committedSequence)) throw new Error("recovery chunks do not cover the committed sequence")
-      const firstAfterAck = chunks.find((chunk) => chunk.sequence > acknowledgedSequence)
+      const unacknowledged = chunksAfterSequence(chunks, acknowledgedSequence)
+      if (!committedChunksAreCovered(unacknowledged, acknowledgedSequence, committedSequence)) throw new Error("recovery chunks do not cover the committed sequence")
+      const firstAfterAck = unacknowledged[0]
       if (firstAfterAck !== undefined && firstAfterAck.sequence - firstAfterAck.data.length !== acknowledgedSequence) throw new Error("recovery chunks do not start at the acknowledgement")
-      if (firstAfterAck === undefined && chunks.length > 0 && chunks.at(-1)?.sequence !== acknowledgedSequence) throw new Error("recovery acknowledgement is not a chunk boundary")
-      const committed = chunks.filter((chunk) => chunk.sequence > acknowledgedSequence && chunk.sequence <= committedSequence)
+      const lastChunk = chunks.at(-1)
+      if (firstAfterAck === undefined && lastChunk !== undefined && lastChunk.sequence < acknowledgedSequence) throw new Error("recovery acknowledgement exceeds stored chunks")
+      const committed = unacknowledged.filter((chunk) => chunk.sequence <= committedSequence)
       const committedBytes = committed.reduce((sum, chunk) => sum + chunk.data.length, 0)
       if (!Number.isSafeInteger(committedBytes) || (this.#maxBytes !== undefined && committedBytes > this.#maxBytes)) throw new Error("recovery chunks exceed the configured byte limit")
       const repairedChunks = serializeChunks(committed)
@@ -360,6 +385,45 @@ export class SessionSpool {
     this.#usedBytes.set(input.sessionId, newTotal)
   }
 
+  /**
+   * Replaces any uncommitted tail, writes a complete operation, then advances
+   * recovery metadata as the commit record. A failure before the last step is
+   * ignored by recovery and safely replaced by a retry.
+   * @param {AppendChunkBatchInput} input - Atomic durable admission input.
+   * @returns {Promise<void>} Completion after the recovery commit.
+   */
+  async appendChunksAndRecoveryState(input) {
+    const session = await this.#readSession(input.sessionId)
+    if (session.metadata.ownerId !== input.ownerId) throw new Error("Chunk owner does not match spool metadata")
+    if (!Number.isSafeInteger(input.previousSequence) || input.previousSequence < 0) throw new RangeError("Previous durable sequence must be a non-negative safe integer")
+    if (!Array.isArray(input.chunks) || input.chunks.length === 0) throw new TypeError("Durable chunk batch must not be empty")
+    const encodedRecovery = `${JSON.stringify(input.recoveryState)}\n`
+    if (Buffer.byteLength(encodedRecovery) > MAX_RECOVERY_STATE_BYTES) throw new Error("Socketduct recovery state exceeds its size limit")
+
+    const createdAt = new Date(session.metadata.createdAt).getTime()
+    const ageMs = this.#now() - createdAt
+    if (this.#maxAgeMs !== undefined && ageMs > this.#maxAgeMs) throw new SpoolQuotaError(`Spool age ${ageMs}ms exceeds max ${this.#maxAgeMs}ms for session ${input.sessionId}`, "SPOOL_AGE_EXCEEDED")
+
+    const stored = await this.#readAllChunks(input.sessionId)
+    const committed = stored.filter((chunk) => chunk.sequence <= input.previousSequence)
+    let sequence = input.previousSequence
+    const additions = input.chunks.map((chunk) => {
+      const data = Buffer.from(chunk.data)
+      if (data.length === 0 || !Number.isSafeInteger(chunk.sequence) || chunk.sequence !== sequence + data.length) throw new Error("Durable chunk batch is not contiguous")
+      sequence = chunk.sequence
+      return {sequence: chunk.sequence, data}
+    })
+    const chunks = [...committed, ...additions]
+    const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.data.length, 0)
+    if (!Number.isSafeInteger(totalBytes) || (this.#maxBytes !== undefined && totalBytes > this.#maxBytes)) throw new SpoolQuotaError(`Spool byte quota exceeded for session ${input.sessionId}: ${totalBytes} / max ${this.#maxBytes}`, "SPOOL_QUOTA_EXCEEDED")
+
+    await this.#writeChunks(input.sessionId, chunks)
+    await writeFileAtomic(join(session.directory, "usage.json"), JSON.stringify({totalBytes}) + "\n", {mode: 0o600})
+    this.#usedBytes.set(input.sessionId, totalBytes)
+    this.#usageLoaded.add(input.sessionId)
+    await this.writeRecoveryState(input.sessionId, input.recoveryState)
+  }
+
   /**
    * @param {string} sessionId - sessionId value.
    * @param {number} acknowledgedSequence - acknowledgedSequence value.
@@ -377,7 +441,8 @@ export class SessionSpool {
    */
   async truncateAcked(sessionId, acknowledgedSequence) {
     const chunks = await this.#readAllChunks(sessionId)
-    const remaining = chunks.filter((chunk) => chunk.sequence > acknowledgedSequence)
+    const byteSequenced = chunks.every((chunk, index) => chunk.data.length <= chunk.sequence && (index === 0 || chunk.sequence - chunk.data.length === chunks[index - 1]?.sequence))
+    const remaining = byteSequenced ? chunksAfterSequence(chunks, acknowledgedSequence) : chunks.filter((chunk) => chunk.sequence > acknowledgedSequence)
     await this.#writeChunks(sessionId, remaining)
     const newTotal = remaining.reduce((sum, chunk) => sum + chunk.data.length, 0)
     const directory = this.#sessionDirectory(sessionId)
@@ -547,6 +612,27 @@ function serializeChunks(chunks) {
   return lines.length === 0 ? "" : `${lines.join("\n")}\n`
 }
 
+/**
+ * Removes an acknowledged prefix, including a byte-granular prefix inside the
+ * first retained physical chunk.
+ * @param {readonly SpoolChunk[]} chunks - Ordered chunks.
+ * @param {number} acknowledgedSequence - Cumulative application-byte ACK.
+ * @returns {SpoolChunk[]} Unacknowledged suffix.
+ */
+function chunksAfterSequence(chunks, acknowledgedSequence) {
+  /** @type {SpoolChunk[]} */
+  const remaining = []
+  for (const chunk of chunks) {
+    if (chunk.sequence <= acknowledgedSequence) continue
+    const start = chunk.sequence - chunk.data.length
+    remaining.push({
+      sequence: chunk.sequence,
+      data: start < acknowledgedSequence ? Buffer.from(chunk.data.subarray(acknowledgedSequence - start)) : Buffer.from(chunk.data)
+    })
+  }
+  return remaining
+}
+
 /**
  * @param {readonly SpoolChunk[]} chunks - Structurally validated physical chunks.
  * @param {number} acknowledgedSequence - Durable ACK boundary.

package/tensorbuzz.yml

@@ -2,7 +2,7 @@ dependency_roots:
   - path: .
 before_install:
   - curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
-  - sudo apt-get install -y docker.io nodejs zstd=1.5.7+dfsg-3
+  - sudo apt-get install -y docker.io nodejs zstd
 before_script:
   - node --version
 environment:

package/test/e2e/reverse-client-recovery-process.test.js

@@ -154,6 +154,9 @@ test("SIGKILLed reverse client process recovers its durable stream while hub gat
   assert.equal(recovered.openFrames, 0)
   assert(/** @type {number} */ (recovered.generation) > /** @type {number} */ (connected.generation))
   assert.equal(targetAccepts, 1)
+  replacement.child.send({type: "acknowledge", bytes: replayedTargetBytes.length})
+  const acknowledged = await waitForMessage(replacement, "acknowledged")
+  assert.equal(acknowledged.sequence, replayedTargetBytes.length)
   await waitUntil(() => Buffer.concat(targetReceived).toString() === "before-killduring-kill", "replay strictly above gateway high-water")
 
   replacement.child.send({type: "write", payload: Buffer.from("after-kill").toString("base64")})

package/test/fixtures/reverse-client-recovery.mjs

@@ -37,6 +37,7 @@ const client = new ReverseGatewayConnection({
 
 const streamOptions = {
   recover: true,
+  manualReceiveAck: true,
   identifier: configuration.identifier,
   sessionName: configuration.sessionName,
   host: "127.0.0.1",
@@ -74,7 +75,8 @@ if (activeSocket !== undefined) {
     identifier: configuration.identifier,
     sessionName: configuration.sessionName,
     host: "127.0.0.1",
-    port: configuration.targetPort
+    port: configuration.targetPort,
+    manualReceiveAck: true
   })
   installSocketEvents(activeSocket)
 }
@@ -86,7 +88,17 @@ process.on("message", (message) => {
     return
   }
   if (message?.type === "write") {
-    activeSocket.write(Buffer.from(message.payload, "base64"), (error) => report("written", {code: error?.code ?? null}))
+    void activeSocket.writeDurable(Buffer.from(message.payload, "base64")).then(
+      () => report("written", {code: null}),
+      (error) => report("written", {code: error?.code ?? "ERROR"})
+    )
+    return
+  }
+  if (message?.type === "acknowledge") {
+    void activeSocket.acknowledgeReceive(message.bytes).then(
+      (sequence) => report("acknowledged", {sequence}),
+      (error) => report("acknowledge-error", {code: error?.code ?? "ERROR"})
+    )
     return
   }
   if (message?.type === "observe-buffer") {

package/test/integration/multiplexed-transport-set.test.js

@@ -431,11 +431,7 @@ test("process replacement recovers a durable stream on its original named gatewa
   t.after(() => { SessionSpool.prototype.readChunksAfter = originalReadChunksAfter })
   replacement = new MultiplexedSocketductTransportSet(setOptions)
   const recovered = replacement.recoverConnection({
-    gatewayId: "starlink",
-    host: "127.0.0.1",
-    port: targetPort,
-    identifier: "gateway_bound_stream_01",
-    sessionName: "gateway-bound"
+    identifier: "gateway_bound_stream_01"
   })
   await recoveryRead
   await new Promise((resolve) => setImmediate(resolve))

package/test/integration/reverse-gateway.test.js

@@ -178,6 +178,7 @@ class HeldWriteTarget extends Duplex {
   /** @param {Buffer} chunk - Written bytes. @param {BufferEncoding} _encoding - Ignored encoding. @param {(error?: Error | null) => void} callback - Completion. @override */
   _write(chunk, _encoding, callback) {
     this.chunks.push(Buffer.from(chunk))
+    this.emit("writeObserved")
     if (this.#held) { callback(); return }
     this.#held = true
     this.releaseFirstWrite = callback
@@ -191,6 +192,19 @@ class HeldWriteTarget extends Duplex {
   }
 }
 
+/** @param {HeldWriteTarget} target - Observed target. @param {number} bytes - Required bytes. */
+async function waitForTargetBytes(target, bytes) {
+  if (Buffer.concat(target.chunks).length >= bytes) return
+  await new Promise((resolve) => {
+    const observe = () => {
+      if (Buffer.concat(target.chunks).length < bytes) return
+      target.off("writeObserved", observe)
+      resolve(undefined)
+    }
+    target.on("writeObserved", observe)
+  })
+}
+
 class ObservedMemoryBudget {
   /** @type {number} */ bytes = 0
   /** @type {number} */ spoolBytes = 0
@@ -350,7 +364,7 @@ test("recovered reverse clients require explicit cold durable identity before an
   const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-recovery-contract-"))
   t.after(() => rm(root, {recursive: true, force: true}))
   const spoolDirectory = join(root, "client-spool")
-  await seedReverseClientRecovery(spoolDirectory, {sendAck: 2}, [
+  await seedReverseClientRecovery(spoolDirectory, {sendAck: 2, manualReceiveAck: true}, [
     {sequence: 2, data: Buffer.from("aa")},
     {sequence: 4, data: Buffer.from("bb")}
   ])
@@ -373,10 +387,17 @@ test("recovered reverse clients require explicit cold durable identity before an
 
   const client = new ReverseGatewayConnection(base)
   t.after(() => client.close())
+  assert.deepEqual(client._inspectRecoveredConnection("recovered_stream_01"), {
+    identifier: "recovered_stream_01",
+    target: {host: "docker-server", port: 2375},
+    sessionName: "durable-reverse-stream",
+    manualReceiveAck: true
+  })
   assert.throws(() => client.createConnection({recover: true, identifier: "recovered_stream_01", host: "docker-server", port: 2375}), /must use registerRecoveredConnection/i)
   assert.throws(() => client.registerRecoveredConnection(/** @type {import('../../src/client/multiplexed-connection.js').VirtualConnectionOptions} */ ({identifier: "recovered_stream_01", host: "docker-server", port: 2375})), /recover: true/i)
   const recovered = client.registerRecoveredConnection({recover: true, identifier: "recovered_stream_01", sessionName: "durable-reverse-stream", host: "docker-server", port: 2375})
   assert.equal(recovered.streamId, 1)
+  assert.equal(recovered.manualReceiveAck, true)
   assert.equal(client.status().physicalState, "configured")
   assert.equal(client.status().connectionGeneration, 41)
   assert.equal(client.status().spoolBytes, 2)
@@ -1310,6 +1331,63 @@ test("reverse client backpressures a write larger than its retained-byte limit",
   socket.destroy()
 })
 
+test("reverse client durable write rejects atomically at limits and remains retryable", async (t) => {
+  const {budget, client, socket, target} = await createBackpressuredClient(t, "durable_write_limit")
+  const oversized = Buffer.alloc(33, 0x6f)
+
+  await assert.rejects(
+    socket.writeDurable(oversized),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_DURABLE_WRITE_LIMIT"
+  )
+  assert.deepEqual(target.chunks, [])
+  assert.equal(client.status().queuedBytes, 0)
+  assert.equal(client.status().spoolBytes, 0)
+  assert.equal(budget.bytes, 0)
+
+  const request = Buffer.alloc(32, 0x72)
+  await socket.writeDurable(request)
+  assert.equal(client.status().queuedBytes, request.length)
+  assert.equal(client.status().spoolBytes, request.length)
+  assert.equal(budget.bytes, request.length)
+  await withTimeout(target.firstWrite, "first atomically admitted request frame")
+  target.release()
+  await withTimeout(waitForTargetBytes(target, request.length), "complete atomically admitted request")
+  assert.deepEqual(Buffer.concat(target.chunks), request)
+  socket.destroy()
+})
+
+test("reverse client durable write exposes no bytes after a partial persistence failure and can retry", async (t) => {
+  const {budget, client, socket, target} = await createBackpressuredClient(t, "durable_write_retry")
+  const originalWriteRecoveryState = SessionSpool.prototype.writeRecoveryState
+  let failAdmissionCommit = true
+  SessionSpool.prototype.writeRecoveryState = async function (/** @type {string} */ identifier, /** @type {Record<string, unknown>} */ state) {
+    if (failAdmissionCommit && identifier.length >= 8 && state.sendSequence === 16) {
+      failAdmissionCommit = false
+      throw Object.assign(new Error("injected recovery commit failure"), {code: "EIO"})
+    }
+    await originalWriteRecoveryState.call(this, identifier, state)
+  }
+  t.after(() => { SessionSpool.prototype.writeRecoveryState = originalWriteRecoveryState })
+
+  const request = Buffer.alloc(16, 0x64)
+  await assert.rejects(
+    socket.writeDurable(request),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_DURABLE_WRITE_PERSISTENCE"
+  )
+  assert.deepEqual(target.chunks, [])
+  assert.equal(client.status().queuedBytes, 0)
+  assert.equal(client.status().spoolBytes, 0)
+  assert.equal(budget.bytes, 0)
+  assert.equal(budget.spoolBytes, 0)
+
+  await socket.writeDurable(request)
+  await withTimeout(target.firstWrite, "retried durable request")
+  target.release()
+  await withTimeout(waitForTargetBytes(target, request.length), "complete retried durable request")
+  assert.deepEqual(Buffer.concat(target.chunks), request)
+  socket.destroy()
+})
+
 test("reverse client chunks a large write to the negotiated stream window", async (t) => {
   const {budget, client, socket, target} = await createBackpressuredClient(t, "negotiated_window", {
     hubWindowBytes: 8,
@@ -1424,6 +1502,85 @@ test("reverse gateway honors the smaller hub receive window", async (t) => {
   socket.destroy()
 })
 
+test("reverse client manual receive ACK advances only after the application commits bytes", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-manual-ack-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, initialWindowBytes: 8, maxFrameBytes: 8})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  /** @type {import('node:net').Socket | undefined} */
+  let targetSocket
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetSocket = socket
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "manual_ack_gateway", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, authorizeTarget: () => true, initialWindowBytes: 8, maxFrameBytes: 8})
+  t.after(() => gateway.close())
+  await gateway.start()
+
+  /** @type {number[]} */
+  const ackSequences = []
+  const spoolDirectory = join(root, "client-spool")
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "manual_ack_client",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-token"},
+    tls,
+    spoolDirectory,
+    initialWindowBytes: 8,
+    maxFrameBytes: 8,
+    createPhysicalSocket: (options) => {
+      const physical = connectTls({host: options.host, port: options.port, ...options.tls})
+      const write = physical.write.bind(physical)
+      physical.write = ((chunk, ...args) => {
+        if (Buffer.isBuffer(chunk) && chunk.length >= 24 && chunk[5] === V3FrameType.ACK) ackSequences.push(Number(chunk.readBigUInt64BE(12)))
+        return Reflect.apply(write, physical, [chunk, ...args])
+      })
+      return physical
+    }
+  })
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({identifier: "manual_ack_stream", host: "127.0.0.1", port: targetPort, manualReceiveAck: true})
+  await onceEvent(socket, "connect")
+  assert(targetSocket !== undefined)
+
+  const received = readBytes(socket, 8)
+  targetSocket.write("response")
+  assert.equal((await withTimeout(received, "manual ACK response")).toString(), "response")
+  assert.deepEqual(ackSequences, [])
+
+  assert.equal(await socket.acknowledgeReceive(3), 3)
+  assert.equal(await socket.acknowledgeReceive(5), 8)
+  assert.deepEqual(ackSequences, [3, 8])
+  assert.throws(
+    () => socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_INVALID_RECEIVE_ACK"
+  )
+  const recovery = JSON.parse(await readFile(join(spoolDirectory, "manual_ack_stream", "recovery.json"), "utf8"))
+  assert.equal(recovery.receiveAck, 8)
+  assert.equal(recovery.manualReceiveAck, true)
+
+  const finalByte = readBytes(socket, 1)
+  targetSocket.write("x")
+  await withTimeout(finalByte, "manual ACK final byte")
+  await client.detach()
+  await assert.rejects(
+    socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_CONNECTION_DETACHED"
+  )
+  await assert.rejects(
+    socket.writeDurable("late-request"),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_CONNECTION_DETACHED"
+  )
+})
+
 test("reverse peers reconnect after graceful hub shutdown", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-hub-restart-"))
   t.after(() => rm(root, {recursive: true, force: true}))

package/test/unit/client/multiplexed-transport-set.test.js

@@ -66,6 +66,8 @@ class FakeMember extends EventEmitter {
     this.createConnectionCalls = []
     /** @type {Record<string, unknown>[]} */
     this.recoveryConnectionCalls = []
+    /** @type {Map<string, {identifier: string, target: {host: string, port: number}, sessionName: string, manualReceiveAck: boolean}>} */
+    this.recoveryDescriptors = new Map()
     this.state = "configured"
     this.generation = 0
     this.physicalConnects = 0
@@ -125,6 +127,11 @@ class FakeMember extends EventEmitter {
     return /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket} */ (/** @type {unknown} */ (socket))
   }
 
+  /** @param {string} identifier - Stable stream identifier. */
+  _inspectRecoveredConnection(identifier) {
+    return this.recoveryDescriptors.get(identifier)
+  }
+
   status() {
     return {
       physicalState: this.state,
@@ -289,8 +296,8 @@ test("route-class members are first-class reverse transports with route-class al
   assert(connectionIds.every((connectionId) => typeof connectionId === "string"))
   assert.equal(new Set(connectionIds).size, 2)
 
-  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "route_stream_01"}))), /exactly one.*gatewayId.*routeClass/i)
-  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({gatewayId: "starlink", routeClass: "zyxel", host: "target.internal", port: 443, identifier: "route_stream_01"}))), /exactly one.*gatewayId.*routeClass/i)
+  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "route_stream_01"}))), (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_RECOVERY_NOT_FOUND")
+  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({gatewayId: "starlink", routeClass: "zyxel", host: "target.internal", port: 443, identifier: "route_stream_01"}))), /at most one.*gatewayId.*routeClass/i)
   assert.throws(() => set.recoverConnection({routeClass: "missing", host: "target.internal", port: 443, identifier: "route_stream_01"}), /unknown routeClass/i)
   const recovered = set.recoverConnection({routeClass: "zyxel", host: "target.internal", port: 443, identifier: "route_stream_01", sessionName: "durable-route"})
   assert.equal(/** @type {{gatewayId?: string}} */ (recovered).gatewayId, undefined)
@@ -858,7 +865,7 @@ test("pending socket end reserves and sends DataView bytes", async () => {
 
 test("recovery requires one original configured selector and registration before start", async () => {
   const {set, members} = fixture()
-  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "stable_stream_01"}))), /gatewayId/i)
+  assert.throws(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet['recoverConnection']>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "stable_stream_01"}))), (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_RECOVERY_NOT_FOUND")
   assert.throws(() => set.recoverConnection({gatewayId: "unknown", host: "target.internal", port: 443, identifier: "stable_stream_01"}), /unknown gatewayId/i)
   assert.throws(() => set.createConnection(/** @type {import('../../../src/client/multiplexed-connection.js').VirtualConnectionOptions} */ (/** @type {unknown} */ ({gatewayId: "zyxel", host: "target.internal", port: 443}))), /recoverConnection/i)
   assert.throws(() => set.createConnection({recover: true, host: "target.internal", port: 443, identifier: "stable_stream_01"}), /recoverConnection/i)
@@ -895,6 +902,46 @@ test("recovery requires one original configured selector and registration before
   await set.close()
 })
 
+test("identifier-only recovery finds exactly one durable member and restores stored options", async () => {
+  const unique = fixture()
+  at(unique.members, 1).recoveryDescriptors.set("stable_stream_05", {
+    identifier: "stable_stream_05",
+    target: {host: "target.internal", port: 443},
+    sessionName: "durable-request",
+    manualReceiveAck: true
+  })
+
+  const recovered = unique.set.recoverConnection({identifier: "stable_stream_05"})
+  assert.equal(gatewayOf(recovered), "zyxel")
+  assert.deepEqual(at(unique.members, 1).recoveryConnectionCalls, [{
+    identifier: "stable_stream_05",
+    target: {host: "target.internal", port: 443},
+    sessionName: "durable-request",
+    manualReceiveAck: true,
+    recover: true
+  }])
+  assert.throws(
+    () => unique.set.recoverConnection({identifier: "missing_stream_01"}),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_RECOVERY_NOT_FOUND"
+  )
+  await unique.set.close()
+
+  const ambiguous = fixture()
+  const descriptor = {
+    identifier: "duplicate_stream_01",
+    target: {host: "target.internal", port: 443},
+    sessionName: "duplicate",
+    manualReceiveAck: false
+  }
+  at(ambiguous.members, 0).recoveryDescriptors.set(descriptor.identifier, descriptor)
+  at(ambiguous.members, 2).recoveryDescriptors.set(descriptor.identifier, descriptor)
+  assert.throws(
+    () => ambiguous.set.recoverConnection({identifier: descriptor.identifier}),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_RECOVERY_AMBIGUOUS"
+  )
+  await ambiguous.set.close()
+})
+
 test("returns the stable selected gatewayId on ordinary and recovered sockets", async () => {
   const {set, members} = fixture()
   const started = set.start()

package/test/unit/client/virtual-socket.test.js

@@ -8,7 +8,7 @@ import {VirtualSocket} from "../../../src/client/virtual-socket.js"
  *
  */
 function fakeConnection() {
-  const calls = {destroyed: 0, ended: 0, resumed: 0, refs: 0, unrefs: 0}
+  const calls = {destroyed: 0, ended: 0, resumed: 0, refs: 0, unrefs: 0, delivered: 0, acknowledged: 0, durableWrites: /** @type {Buffer[]} */ ([])}
   return {
     calls,
     connection: /** @type {import('../../../src/client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ ({
@@ -25,6 +25,16 @@ function fakeConnection() {
       _endStream: (_id, callback) => { calls.ended += 1; callback() },
       _destroyStream: () => { calls.destroyed += 1 },
       _resumeReadable: () => { calls.resumed += 1 },
+      _deliverReadable: (/** @type {number} */ _id, /** @type {number} */ bytes) => { calls.delivered += bytes },
+      _acknowledgeReadable: (/** @type {number} */ _id, /** @type {number} */ bytes) => {
+        assert(bytes <= calls.delivered - calls.acknowledged)
+        calls.acknowledged += bytes
+        return Promise.resolve(calls.acknowledged)
+      },
+      _writeDurableStream: (/** @type {number} */ _id, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) => {
+        calls.durableWrites.push(Buffer.from(data))
+        callback()
+      },
       physicalAddress: () => ({address: "127.0.0.1", port: 43210}),
       ref: () => { calls.refs += 1 },
       unref: () => { calls.unrefs += 1 }
@@ -96,3 +106,115 @@ test("VirtualSocket pause/resume, timeout, data and half-close remain stream-loc
   assert(fake.calls.resumed > 0)
   socket.destroy()
 })
+
+test("VirtualSocket exposes opt-in manual receive ACK and durable write contracts", async () => {
+  const fake = fakeConnection()
+  const socket = new VirtualSocket(fake.connection, 7, {
+    host: "127.0.0.1",
+    port: 80,
+    manualReceiveAck: true
+  })
+  socket._markConnected()
+
+  const acknowledged = new Promise((resolve, reject) => {
+    socket.once("data", (chunk) => {
+      socket.acknowledgeReceive(chunk.length).then(resolve, reject)
+    })
+  })
+  socket._receive(Buffer.from("response"))
+  assert.equal(await acknowledged, 8)
+  assert.equal(fake.calls.delivered, 8)
+  assert.equal(fake.calls.acknowledged, 8)
+
+  await socket.writeDurable(new Uint8Array(Buffer.from("request")))
+  assert.deepEqual(fake.calls.durableWrites, [Buffer.from("request")])
+  assert.equal(socket.bytesWritten, 7)
+  assert.throws(
+    () => socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_INVALID_RECEIVE_ACK"
+  )
+  const closed = new Promise((resolve) => socket.once("close", resolve))
+  socket.destroy()
+  await closed
+  await assert.rejects(
+    socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "ERR_STREAM_DESTROYED"
+  )
+})
+
+test("VirtualSocket orders durable writes behind queued ordinary writes", async () => {
+  const fake = fakeConnection()
+  /** @type {string[]} */
+  const delivered = []
+  /** @type {(() => void) | undefined} */
+  let releaseFirst
+  const connection = /** @type {{_writeStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void, _writeDurableStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void}} */ (/** @type {unknown} */ (fake.connection))
+  connection._writeStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    if (data.toString() === "A") releaseFirst = callback
+    else callback()
+  }
+  connection._writeDurableStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    callback()
+  }
+  const socket = new VirtualSocket(fake.connection, 9, {host: "127.0.0.1", port: 80})
+
+  const first = new Promise((resolve, reject) => socket.write("A", (error) => error ? reject(error) : resolve(undefined)))
+  const second = new Promise((resolve, reject) => socket.write("B", (error) => error ? reject(error) : resolve(undefined)))
+  const durable = socket.writeDurable("C")
+  assert(releaseFirst !== undefined)
+  releaseFirst()
+  await Promise.all([first, second, durable])
+
+  assert.deepEqual(delivered, ["A", "B", "C"])
+  assert.equal(socket.bytesWritten, 3)
+  socket.destroy()
+})
+
+test("VirtualSocket rejects durable writes after end while ordinary writes remain queued", async () => {
+  const fake = fakeConnection()
+  /** @type {string[]} */
+  const delivered = []
+  /** @type {(() => void) | undefined} */
+  let releaseFirst
+  const connection = /** @type {{_writeStream: (id: number, data: Buffer, callback: (error?: Error | null) => void) => void}} */ (/** @type {unknown} */ (fake.connection))
+  connection._writeStream = (_id, data, callback) => {
+    delivered.push(data.toString())
+    if (data.toString() === "A") releaseFirst = callback
+    else callback()
+  }
+  const socket = new VirtualSocket(fake.connection, 11, {host: "127.0.0.1", port: 80})
+
+  const first = new Promise((resolve, reject) => socket.write("A", (error) => error ? reject(error) : resolve(undefined)))
+  const second = new Promise((resolve, reject) => socket.write("B", (error) => error ? reject(error) : resolve(undefined)))
+  const finished = new Promise((resolve) => socket.once("finish", resolve))
+  socket.end()
+  const rejected = assert.rejects(
+    socket.writeDurable("late"),
+    (error) => /** @type {{code?: string}} */ (error).code === "ERR_STREAM_WRITE_AFTER_END"
+  )
+
+  assert(releaseFirst !== undefined)
+  releaseFirst()
+  await Promise.all([first, second, finished, rejected])
+  assert.deepEqual(delivered, ["A", "B"])
+  assert.deepEqual(fake.calls.durableWrites, [])
+  socket.destroy()
+})
+
+test("VirtualSocket keeps manual ACK opt-in and reports unsupported durable admission", async () => {
+  const fake = fakeConnection()
+  delete /** @type {{_writeDurableStream?: unknown}} */ (fake.connection)._writeDurableStream
+  const socket = new VirtualSocket(fake.connection, 9, {host: "127.0.0.1", port: 80})
+
+  assert.throws(
+    () => socket.acknowledgeReceive(1),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_MANUAL_ACK_DISABLED"
+  )
+  await assert.rejects(
+    socket.writeDurable("request"),
+    (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_DURABLE_WRITE_UNSUPPORTED"
+  )
+  socket.destroy()
+})