socketduct 0.1.19 → 0.1.21

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
@@ -307,11 +321,50 @@ test("reverse client contains a TLS AUTH write race inside the transport", async
   await assert.rejects(connecting, /closed/i)
 })
 
+test("fatal hub GOAWAY preserves validated attribution on the public client error", async (t) => {
+  /** @type {AuthWriteSocket | undefined} */
+  let physical
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "fatal_goaway_attribution_client",
+    hub: {host: "127.0.0.1", port: 3100, token: "client-token"},
+    tls: {servername: "localhost"},
+    continuousReconnect: false,
+    createPhysicalSocket: () => {
+      physical = new AuthWriteSocket()
+      return /** @type {import('node:tls').TLSSocket} */ (/** @type {unknown} */ (physical))
+    }
+  })
+  t.after(() => client.close())
+  const connecting = client.connect()
+  physical?.emit("secureConnect")
+  physical?.emit("data", encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({
+    code: "PROTOCOL_VIOLATION",
+    disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
+    disconnectReason: "protocol_violation",
+    incidentOrigin: "reverse_hub",
+    physicalRole: "client",
+    clientConnectionGeneration: 1,
+    fanOutCount: 0,
+    resumeSuccessCount: 0,
+    terminalStreamCount: 0
+  })))
+  /** @type {Error & Record<string, unknown> | undefined} */
+  let rejection
+  await assert.rejects(withTimeout(connecting, "fatal attributed GOAWAY"), (error) => {
+    rejection = /** @type {Error & Record<string, unknown>} */ (error)
+    return rejection.code === "PROTOCOL_VIOLATION"
+  })
+  assert.equal(rejection?.disconnectIncidentId, "AAAAAAAAAAAAAAAAAAAAAA")
+  assert.equal(rejection?.disconnectReason, "protocol_violation")
+  assert.equal(rejection?.incidentOrigin, "reverse_hub")
+})
+
 test("recovered reverse clients require explicit cold durable identity before any physical attempt", async (t) => {
   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")}
   ])
@@ -334,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)
@@ -1271,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,
@@ -1385,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}))
@@ -2168,6 +2364,143 @@ test("an expired reverse resume window fails the logical stream once and release
   assert.equal(targets[0]?.destroyed, true)
 })
 
+test("one gateway disconnect incident preserves physical cause across fan-out and terminal resume errors", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-attribution-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-attribution-token"}, {username: "app", token: "client-attribution-token"}])
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const hubEvents = []
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const gatewayEvents = []
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const clientEvents = []
+  const hub = await startReverseGatewayHub({
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    authorizeGateway: () => true,
+    authorizeClientGateway: () => true,
+    authorizeOpen: () => true,
+    resumeWindowMs: 40,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { hubEvents.push({event, ...fields}) }},
+    connectionFingerprint: {key: Buffer.alloc(32, 0x5a), keyEpoch: "test-epoch"}
+  })
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const targets = []
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "low_entropy_gateway_connection",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-attribution-token"},
+    tls,
+    authorizeTarget: () => true,
+    reconnectDelayMs: 150,
+    maxReconnectDelayMs: 150,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { gatewayEvents.push({event, ...fields}) }},
+    createTargetConnection: () => {
+      const target = new InterruptibleTarget()
+      targets.push(target)
+      return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (target))
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "low_entropy_client_connection",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-attribution-token"},
+    tls,
+    reconnectDelayMs: 5,
+    maxReconnectDelayMs: 10,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { clientEvents.push({event, ...fields}) }}
+  })
+  t.after(() => client.close())
+  await client.connect()
+  const sockets = [client.createConnection({host: "target", port: 2375}), client.createConnection({host: "target", port: 2375})]
+  await Promise.all(sockets.map((socket) => onceEvent(socket, "connect")))
+  const terminalErrors = sockets.map((socket) => nextError(socket))
+
+  await hub.closeActiveGateway("o2")
+  const errors = /** @type {Array<Error & Record<string, unknown>>} */ (await Promise.all(terminalErrors))
+  assert.deepEqual(errors.map((error) => error.code), ["RESUME_WINDOW_EXPIRED", "RESUME_WINDOW_EXPIRED"])
+  assert.equal(new Set(errors.map((error) => error.disconnectIncidentId)).size, 1)
+  for (const error of errors) {
+    assert.match(/** @type {string} */ (error.disconnectIncidentId), /^[A-Za-z0-9_-]{22}$/)
+    assert.equal(error.disconnectReason, "unknown_transport_close")
+    assert.equal(error.incidentOrigin, "reverse_hub")
+    assert.equal(error.physicalRole, "gateway")
+    assert.equal(typeof error.clientConnectionGeneration, "number")
+    assert.equal(typeof error.gatewayConnectionGeneration, "number")
+    assert.equal(error.fanOutCount, 2)
+  }
+  const detached = hubEvents.find(({event, physicalRole}) => event === "reverse_hub.physical_detached" && physicalRole === "gateway")
+  assert(detached !== undefined)
+  assert.equal(detached.disconnectIncidentId, /** @type {Error & Record<string, unknown>} */ (errors[0]).disconnectIncidentId)
+  assert.match(/** @type {string} */ (detached.connectionFingerprint), /^[a-f0-9]{32}$/)
+  assert.equal(detached.fingerprintKeyEpoch, "test-epoch")
+  assert(hubEvents.some(({event, fanOutCount}) => event === "reverse_hub.streams_interrupted" && fanOutCount === 2))
+  assert(hubEvents.some(({event, terminalStreamCount}) => event === "reverse_hub.streams_reset" && terminalStreamCount === 2))
+  assert(clientEvents.some(({event}) => event === "reverse_client.physical_detached"))
+  assert(gatewayEvents.some(({event}) => event === "reverse_gateway.physical_detached"))
+  assert.equal(targets.length, 2)
+  assert.doesNotMatch(JSON.stringify([hubEvents, gatewayEvents, clientEvents]), /low_entropy_(?:gateway|client)_connection|attribution-token/)
+})
+
+test("peer GOAWAY classification and hub attribution reach terminal non-resumable RESET", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-terminal-attribution-"))
+  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"}])
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const hubEvents = []
+  const hub = await startReverseGatewayHub({
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    authorizeGateway: () => true,
+    authorizeClientGateway: () => true,
+    authorizeOpen: () => true,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { hubEvents.push({event, ...fields}) }}
+  })
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "terminal_attribution_gateway",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"},
+    tls,
+    authorizeTarget: () => true,
+    createTargetConnection: () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (new InterruptibleTarget())),
+    createPhysicalSocket: (options) => {
+      const physical = connectTls({host: options.host, port: options.port, ...options.tls})
+      const originalWrite = physical.write.bind(physical)
+      physical.write = /** @type {typeof physical.write} */ ((chunk, ...args) => {
+        if (!Buffer.isBuffer(chunk) || chunk[5] !== V3FrameType.GOAWAY) return Reflect.apply(originalWrite, physical, [chunk, ...args])
+        const safeGoaway = encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({code: "GATEWAY_MAINTENANCE", disconnectIncidentId: "BBBBBBBBBBBBBBBBBBBBBB"}))
+        return Reflect.apply(originalWrite, physical, [safeGoaway, ...args])
+      })
+      return physical
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "terminal_attribution_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, continuousReconnect: false})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({host: "target", port: 2375})
+  await onceEvent(socket, "connect")
+  const terminal = nextError(socket)
+  await gateway.close()
+  const error = /** @type {Error & Record<string, unknown>} */ (await withTimeout(terminal, "terminal peer GOAWAY reset"))
+  assert.equal(error.code, "GATEWAY_MAINTENANCE")
+  assert.equal(error.disconnectReason, "peer_goaway")
+  assert.equal(error.incidentOrigin, "reverse_hub")
+  assert.equal(error.physicalRole, "gateway")
+  assert.equal(error.fanOutCount, 1)
+  assert.equal(error.terminalStreamCount, 1)
+  assert.notEqual(error.disconnectIncidentId, "BBBBBBBBBBBBBBBBBBBBBB")
+  assert(hubEvents.some(({event, terminalStreamCount}) => event === "reverse_hub.streams_reset" && terminalStreamCount === 1), JSON.stringify(hubEvents))
+})
+
 test("reverse mode enforces verified TLS and stream resource bounds", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-limits-"))
   const wrongRoot = await mkdtemp(join(tmpdir(), "socketduct-reverse-wrong-ca-"))

package/test/integration/reverse-route-class.test.js

@@ -364,7 +364,12 @@ test("a backpressured gateway does not block DATA or a new OPEN for another rout
     t.after(() => socket.destroy())
     return nextError(socket)
   })
-  assert.equal((await withTimeout(streamAError, "gateway A output limit")).code, "OUTPUT_BACKPRESSURE_LIMIT")
+  const outputError = /** @type {Error & Record<string, unknown>} */ (await withTimeout(streamAError, "gateway A output limit"))
+  assert.equal(outputError.code, "OUTPUT_BACKPRESSURE_LIMIT")
+  assert.equal(outputError.disconnectReason, "output_backpressure_limit")
+  assert.equal(outputError.incidentOrigin, "reverse_hub")
+  assert.equal(outputError.physicalRole, "gateway")
+  assert.match(/** @type {string} */ (outputError.disconnectIncidentId), /^[A-Za-z0-9_-]{22}$/)
   await withTimeout(Promise.all(queuedAErrors), "queued gateway A stream cleanup")
   assert.equal(await exchange(streamB, "after-limit"), "b:after-limit")
   assert.equal(hub.status().healthyGateways, 1)

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()
+})

package/test/unit/config/docker-gateway-files.test.js

@@ -36,6 +36,8 @@ test("TensorBuzz exclusively owns verification and container build validation",
   const packageMetadata = JSON.parse(packageJson)
 
   assert.deepEqual(workflowNames, [])
+  assert.match(tensorbuzz, /^dependency_roots:\n {2}- path: \.$/m)
+  assert.doesNotMatch(tensorbuzz, /^\s*- npm ci$/m)
   assert.match(tensorbuzz, /DOCKER_HOST: "tcp:\/\/docker_server:2375"/)
   assert.match(tensorbuzz, /docker_server:\n\s+image: "docker:[^"]+-dind"/)
   assert.match(tensorbuzz, /privileged: true/)