socketduct 0.1.24 → 0.1.26

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

@@ -1,9 +1,8 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/no-undefined-types, jsdoc/require-param, jsdoc/require-returns */
-import assert from "node:assert/strict"
+import {describe, expect, it} from "@velocious/testing"
 import {EventEmitter} from "node:events"
 import {join} from "node:path"
 import {Duplex} from "node:stream"
-import test from "node:test"
 
 import {
   MultiplexedSocketductTransportSet,
@@ -71,6 +70,7 @@ class FakeMember extends EventEmitter {
     this.state = "configured"
     this.generation = 0
     this.physicalConnects = 0
+    this.gatewayUnavailable = false
     /** @type {Promise<void>} */
     this.connectPromise = new Promise((resolve, reject) => {
       this.resolveConnect = resolve
@@ -135,6 +135,7 @@ class FakeMember extends EventEmitter {
   status() {
     return {
       physicalState: this.state,
+      gatewayUnavailable: this.gatewayUnavailable,
       connectionGeneration: this.generation,
       physicalConnects: this.physicalConnects,
       reconnectAttempts: this.state === "reconnecting" ? 1 : 0,
@@ -206,11 +207,11 @@ function gatewayOf(socket) {
   return /** @type {{gatewayId: string}} */ (socket).gatewayId
 }
 
-/** @template T @param {T[]} values - Values. @param {number} index - Index. @returns {T} */
+/** @template T @param {Array<T | undefined>} values - Values. @param {number} index - Index. @returns {T} */
 function at(values, index) {
   const value = values[index]
-  assert(value !== undefined)
-  return value
+  expect(value).toBeDefined()
+  return /** @type {T} */ (value)
 }
 
 /** @param {EventEmitter} emitter - Source. @param {string} event - Event. @returns {Promise<unknown[]>} */
@@ -222,785 +223,897 @@ function onceEvent(emitter, event) {
 function memberPairs(members) {
   return members.map((member) => {
     const {connectionId, spoolDirectory} = /** @type {import('../../../src/client/multiplexed-connection.js').MultiplexedConnectionOptions} */ (member.options)
-    assert(typeof connectionId === "string")
-    assert(typeof spoolDirectory === "string")
-    return [connectionId, spoolDirectory]
+    expect(connectionId).toEqual(expect.any(String))
+    expect(spoolDirectory).toEqual(expect.any(String))
+    if (connectionId === undefined || spoolDirectory === undefined) throw new Error("expected connectionId and spoolDirectory to be defined")
+    return /** @type {[string, string]} */ ([connectionId, spoolDirectory])
   })
 }
 
-test("validates stable gateway identities, pinned endpoints, and process limits", () => {
-  for (const gatewayId of ["", " ../wan ", "wan/../../escape", "a", "x".repeat(65)]) {
-    assert.throws(() => new MultiplexedSocketductTransportSet(options({
-      gateways: [{gatewayId, endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}}}]
-    })), /gatewayId/i)
-  }
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({
-    gateways: [
-      {gatewayId: "duplicate", endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}}},
-      {gatewayId: "duplicate", endpoint: {relay: {host: "127.0.0.1", port: 3102, token: "secret"}}}
-    ]
-  })), /duplicate gatewayId/i)
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({
-    // @ts-expect-error Deliberately malformed entry must fail at runtime.
-    gateways: [{gatewayId: "starlink", relay: {host: "127.0.0.1", port: 3101, token: "secret"}}]
-  })), /endpoint/i)
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({
-    // @ts-expect-error Deliberately malformed port must fail at runtime.
-    gateways: [{gatewayId: "starlink", endpoint: {relay: {host: "127.0.0.1", port: "3101", token: "secret"}}}]
-  })), /host, port, and token/i)
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({
-    gateways: [{
-      gatewayId: "starlink",
-      // @ts-expect-error Misspelled pinning factory must fail instead of being ignored.
-      endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}, physicalSocketFactory: () => {}}
-    }]
-  })), /unknown endpoint field/i)
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({
-    gateways: [
-      {gatewayId: "starlink", endpoint: {relay: {host: "relay.example", port: 3101, token: "secret"}}},
-      {gatewayId: "zyxel", endpoint: {relay: {host: "relay.example", port: 3101, token: "secret"}}}
-    ]
-  })), /same unpinned endpoint/i)
-  assert.throws(() => new MultiplexedSocketductTransportSet(options({minimumReadyMembers: 4})), /minimumReadyMembers/i)
-  for (const name of ["maxTotalBufferBytes", "maxTotalSpoolBytes", "maxTotalQueuedBytes", "maxPendingOpens"]) {
-    assert.throws(() => new MultiplexedSocketductTransportSet(options({[name]: "1024"})), new RegExp(name))
-  }
-})
+describe("multiplexed transport set", () => {
+  it("validates stable gateway identities, pinned endpoints, and process limits", () => {
+    for (const gatewayId of ["", " ../wan ", "wan/../../escape", "a", "x".repeat(65)]) {
+      expect(() => new MultiplexedSocketductTransportSet(options({
+        gateways: [{gatewayId, endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}}}]
+      }))).toThrow(/gatewayId/i)
+    }
+    expect(() => new MultiplexedSocketductTransportSet(options({
+      gateways: [
+        {gatewayId: "duplicate", endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}}},
+        {gatewayId: "duplicate", endpoint: {relay: {host: "127.0.0.1", port: 3102, token: "secret"}}}
+      ]
+    }))).toThrow(/duplicate gatewayId/i)
+    expect(() => new MultiplexedSocketductTransportSet(options({
+      // @ts-expect-error Deliberately malformed entry must fail at runtime.
+      gateways: [{gatewayId: "starlink", relay: {host: "127.0.0.1", port: 3101, token: "secret"}}]
+    }))).toThrow(/endpoint/i)
+    expect(() => new MultiplexedSocketductTransportSet(options({
+      // @ts-expect-error Deliberately malformed port must fail at runtime.
+      gateways: [{gatewayId: "starlink", endpoint: {relay: {host: "127.0.0.1", port: "3101", token: "secret"}}}]
+    }))).toThrow(/host, port, and token/i)
+    expect(() => new MultiplexedSocketductTransportSet(options({
+      gateways: [{
+        gatewayId: "starlink",
+        // @ts-expect-error Misspelled pinning factory must fail instead of being ignored.
+        endpoint: {relay: {host: "127.0.0.1", port: 3101, token: "secret"}, physicalSocketFactory: () => {}}
+      }]
+    }))).toThrow(/unknown endpoint field/i)
+    expect(() => new MultiplexedSocketductTransportSet(options({
+      gateways: [
+        {gatewayId: "starlink", endpoint: {relay: {host: "relay.example", port: 3101, token: "secret"}}},
+        {gatewayId: "zyxel", endpoint: {relay: {host: "relay.example", port: 3101, token: "secret"}}}
+      ]
+    }))).toThrow(/same unpinned endpoint/i)
+    expect(() => new MultiplexedSocketductTransportSet(options({minimumReadyMembers: 4}))).toThrow(/minimumReadyMembers/i)
+    for (const name of ["maxTotalBufferBytes", "maxTotalSpoolBytes", "maxTotalQueuedBytes", "maxPendingOpens"]) {
+      expect(() => new MultiplexedSocketductTransportSet(options({[name]: "1024"}))).toThrow(new RegExp(name))
+    }
+  })
 
-test("route-class members are first-class reverse transports with route-class allocation metadata", async () => {
-  /** @type {FakeMember[]} */
-  const members = []
-  const set = new MultiplexedSocketductTransportSet(/** @type {import('../../../src/client/multiplexed-transport-set.js').TransportSetOptions} */ (/** @type {unknown} */ ({
-    connectionId: "route_class_process_identity",
-    minimumReadyMembers: 1,
-    routeClasses: [
-      {routeClass: "starlink", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "starlink-token"}, tls: {servername: "hub.example"}}},
-      {routeClass: "zyxel", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "zyxel-token"}, tls: {servername: "hub.example"}}}
-    ]
-  })), {
-    createMember(memberOptions, routeClass) {
-      const member = new FakeMember(memberOptions, routeClass, undefined)
-      members.push(member)
-      return member
+  it("route-class members are first-class reverse transports with route-class allocation metadata", async () => {
+    /** @type {FakeMember[]} */
+    const members = []
+    const set = new MultiplexedSocketductTransportSet(/** @type {import('../../../src/client/multiplexed-transport-set.js').TransportSetOptions} */ (/** @type {unknown} */ ({
+      connectionId: "route_class_process_identity",
+      minimumReadyMembers: 1,
+      routeClasses: [
+        {routeClass: "starlink", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "starlink-token"}, tls: {servername: "hub.example"}}},
+        {routeClass: "zyxel", endpoint: {reverseHub: {host: "hub.example", port: 3100, token: "zyxel-token"}, tls: {servername: "hub.example"}}}
+      ]
+    })), {
+      createMember(memberOptions, routeClass) {
+        const member = new FakeMember(memberOptions, routeClass, undefined)
+        members.push(member)
+        return member
+      }
+    })
+
+    expect(members.map((member) => {
+      const memberOptions = /** @type {import('../../../src/reverse/client.js').ReverseGatewayConnectionOptions} */ (member.options)
+      return {gatewayId: memberOptions.gatewayId, routeClass: memberOptions.routeClass}
+    })).toEqual([
+      {gatewayId: undefined, routeClass: "starlink"},
+      {gatewayId: undefined, routeClass: "zyxel"}
+    ])
+    const connectionIds = members.map((member) => member.options.connectionId)
+    expect(connectionIds.every((connectionId) => typeof connectionId === "string")).toBeTruthy()
+    expect(new Set(connectionIds).size).toBe(2)
+
+    let notFoundError
+    try {
+      set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet["recoverConnection"]>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "route_stream_01"})))
+    } catch (error) {
+      notFoundError = /** @type {Error} */ (error)
     }
+    expect(notFoundError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (notFoundError).code).toBe("SOCKETDUCT_RECOVERY_NOT_FOUND")
+    expect(() => set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet["recoverConnection"]>[0]} */ (/** @type {unknown} */ ({gatewayId: "starlink", routeClass: "zyxel", host: "target.internal", port: 443, identifier: "route_stream_01"})))).toThrow(/at most one.*gatewayId.*routeClass/i)
+    expect(() => set.recoverConnection({routeClass: "missing", host: "target.internal", port: 443, identifier: "route_stream_01"})).toThrow(/unknown routeClass/i)
+    const recovered = set.recoverConnection({routeClass: "zyxel", host: "target.internal", port: 443, identifier: "route_stream_01", sessionName: "durable-route"})
+    expect(/** @type {{gatewayId?: string}} */ (recovered).gatewayId).toBe(undefined)
+    expect(/** @type {{routeClass?: string}} */ (recovered).routeClass).toBe("zyxel")
+    expect(Object.getOwnPropertyDescriptor(recovered, "routeClass")?.writable).toBe(false)
+    expect(members.map((member) => member.opens)).toEqual([0, 1])
+    expect(/** @type {{recover?: unknown}} */ (at(members, 1).recoveryConnectionCalls[0]).recover).toBe(true)
+    expect(Object.hasOwn(/** @type {object} */ (at(members, 1).recoveryConnectionCalls[0]), "routeClass")).toBe(false)
+
+    const started = set.start()
+    at(members, 0).ready()
+    await started
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    expect(/** @type {{gatewayId?: string}} */ (socket).gatewayId).toBe(undefined)
+    expect(/** @type {{routeClass?: string}} */ (socket).routeClass).toBe("starlink")
+    expect(set.status().members.map((member) => ({gatewayId: member.gatewayId, routeClass: member.routeClass}))).toEqual([
+      {gatewayId: undefined, routeClass: "starlink"},
+      {gatewayId: undefined, routeClass: "zyxel"}
+    ])
+    await set.close()
   })
 
-  assert.deepEqual(members.map((member) => {
-    const memberOptions = /** @type {import('../../../src/reverse/client.js').ReverseGatewayConnectionOptions} */ (member.options)
-    return {gatewayId: memberOptions.gatewayId, routeClass: memberOptions.routeClass}
-  }), [
-    {gatewayId: undefined, routeClass: "starlink"},
-    {gatewayId: undefined, routeClass: "zyxel"}
-  ])
-  const connectionIds = members.map((member) => member.options.connectionId)
-  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"}))), (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)
-  assert.equal(/** @type {{routeClass?: string}} */ (recovered).routeClass, "zyxel")
-  assert.equal(Object.getOwnPropertyDescriptor(recovered, "routeClass")?.writable, false)
-  assert.deepEqual(members.map((member) => member.opens), [0, 1])
-  assert.equal(/** @type {{recover?: unknown}} */ (at(members, 1).recoveryConnectionCalls[0]).recover, true)
-  assert.equal(Object.hasOwn(/** @type {object} */ (at(members, 1).recoveryConnectionCalls[0]), "routeClass"), false)
-
-  const started = set.start()
-  at(members, 0).ready()
-  await started
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  assert.equal(/** @type {{gatewayId?: string}} */ (socket).gatewayId, undefined)
-  assert.equal(/** @type {{routeClass?: string}} */ (socket).routeClass, "starlink")
-  assert.deepEqual(set.status().members.map((member) => ({gatewayId: member.gatewayId, routeClass: member.routeClass})), [
-    {gatewayId: undefined, routeClass: "starlink"},
-    {gatewayId: undefined, routeClass: "zyxel"}
-  ])
-  await set.close()
-})
+  it("logs transport-set startup, generation replacement, and terminal failure without error text", async () => {
+    /** @type {Array<{event: string} & Record<string, unknown>>} */
+    const entries = []
+    const logger = {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => entries.push({event, ...fields})}
+    const {set, members} = fixture({logger})
+    expect(members.every((member) => member.options.logger === logger)).toBeTruthy()
 
-test("logs transport-set startup, generation replacement, and terminal failure without error text", async () => {
-  /** @type {Array<{event: string} & Record<string, unknown>>} */
-  const entries = []
-  const logger = {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => entries.push({event, ...fields})}
-  const {set, members} = fixture({logger})
-  assert(members.every((member) => member.options.logger === logger))
-
-  const started = set.start()
-  at(members, 0).ready()
-  await started
-  at(members, 0).degrade(Object.assign(new Error("alphabeticsecret eyJhbGciOiJIUzI1NiJ9.private.signature"), {code: "ECONNRESET"}))
-  at(members, 0).ready()
-  at(members, 0).fail(Object.assign(new Error("first lowentropysecret"), {code: "GATEWAY_DISCONNECTED"}))
-  at(members, 1).fail(new Error("second alphabeticsecret"))
-  at(members, 2).fail(new Error("third eyJhbGciOiJIUzI1NiJ9.private.signature"))
-
-  assert(entries.some(({event}) => event === "transport_set.started"))
-  assert(entries.some(({event, gatewayId, generation}) => event === "transport_set.member_state" && gatewayId === "starlink" && generation === 1))
-  assert(entries.some(({event, gatewayId, generation}) => event === "transport_set.member_replaced" && gatewayId === "starlink" && generation === 2))
-  assert(entries.some(({event}) => event === "transport_set.terminal_failure"))
-  const serialized = JSON.stringify(entries)
-  assert.doesNotMatch(serialized, /alphabeticsecret|lowentropysecret|eyJhbGci|127\.0\.0\.1|secret/)
-  await set.close()
-})
+    const started = set.start()
+    at(members, 0).ready()
+    await started
+    at(members, 0).degrade(Object.assign(new Error("alphabeticsecret eyJhbG...ture"), {code: "ECONNRESET"}))
+    at(members, 0).ready()
+    at(members, 0).fail(Object.assign(new Error("first lowentropysecret"), {code: "GATEWAY_DISCONNECTED"}))
+    at(members, 1).fail(new Error("second alphabeticsecret"))
+    at(members, 2).fail(new Error("third eyJhbG...ture"))
+
+    expect(entries.some(({event}) => event === "transport_set.started")).toBeTruthy()
+    expect(entries.some(({event, gatewayId, generation}) => event === "transport_set.member_state" && gatewayId === "starlink" && generation === 1)).toBeTruthy()
+    expect(entries.some(({event, gatewayId, generation}) => event === "transport_set.member_replaced" && gatewayId === "starlink" && generation === 2)).toBeTruthy()
+    expect(entries.some(({event}) => event === "transport_set.terminal_failure")).toBeTruthy()
+    const serialized = JSON.stringify(entries)
+    expect(serialized).not.toMatch(/alphabeticsecret|lowentropysecret|eyJhbGci|127\.0\.0\.1|secret/)
+    await set.close()
+  })
 
-test("derives stable isolated connection identities and spool namespaces per gateway", () => {
-  const first = fixture()
-  const second = fixture()
-  const firstPairs = memberPairs(first.members)
-  const secondPairs = memberPairs(second.members)
-  assert.deepEqual(firstPairs, secondPairs)
-  assert.equal(new Set(firstPairs.map(([connectionId]) => connectionId)).size, 3)
-  assert.equal(new Set(firstPairs.map(([, spoolDirectory]) => spoolDirectory)).size, 3)
-  const baseSpoolDirectory = options().spoolDirectory
-  assert(typeof baseSpoolDirectory === "string")
-  for (const [connectionId, spoolDirectory] of firstPairs) {
-    assert.match(connectionId, /^[A-Za-z0-9_-]{8,128}$/)
-    assert.equal(spoolDirectory.startsWith(join(baseSpoolDirectory, "gateway-")), true)
-    assert.equal(spoolDirectory.includes(".."), false)
-  }
-})
+  it("derives stable isolated connection identities and spool namespaces per gateway", () => {
+    const first = fixture()
+    const second = fixture()
+    const firstPairs = memberPairs(first.members)
+    const secondPairs = memberPairs(second.members)
+    expect(firstPairs).toEqual(secondPairs)
+    expect(new Set(firstPairs.map(([connectionId]) => connectionId)).size).toBe(3)
+    expect(new Set(firstPairs.map(([, spoolDirectory]) => spoolDirectory)).size).toBe(3)
+    const baseSpoolDirectory = options().spoolDirectory
+    expect(baseSpoolDirectory).toEqual(expect.any(String))
+    if (baseSpoolDirectory === undefined) throw new Error("expected the fixture spool directory")
+    for (const [connectionId, spoolDirectory] of firstPairs) {
+      expect(connectionId).toMatch(/^[A-Za-z0-9_-]{8,128}$/)
+      expect(spoolDirectory.startsWith(join(baseSpoolDirectory, "gateway-"))).toBe(true)
+      expect(spoolDirectory.includes("..")).toBe(false)
+    }
+  })
 
-test("warms every configured member concurrently and coalesces start at minimum readiness", async () => {
-  const {set, members} = fixture({minimumReadyMembers: 1})
-  const firstStart = set.start()
-  const secondStart = set.start()
-  assert.equal(firstStart, secondStart)
-  assert.deepEqual(members.map((member) => member.connectCalls), [1, 1, 1])
-  assert.equal(set.status().connectingMembers, 3)
-
-  at(members, 1).ready()
-  await firstStart
-  assert.equal(set.status().readyMembers, 1)
-  assert.equal(set.status().state, "degraded")
-  assert.deepEqual(members.map((member) => member.connectCalls), [1, 1, 1])
-
-  at(members, 0).ready()
-  at(members, 2).ready()
-  assert.equal(set.status().readyMembers, 3)
-  assert.equal(set.status().state, "ready")
-  await set.close()
-})
+  it("warms every configured member concurrently and coalesces start at minimum readiness", async () => {
+    const {set, members} = fixture({minimumReadyMembers: 1})
+    const firstStart = set.start()
+    const secondStart = set.start()
+    expect(firstStart).toBe(secondStart)
+    expect(members.map((member) => member.connectCalls)).toEqual([1, 1, 1])
+    expect(set.status().connectingMembers).toBe(3)
+
+    at(members, 1).ready()
+    await firstStart
+    expect(set.status().readyMembers).toBe(1)
+    expect(set.status().state).toBe("degraded")
+    expect(members.map((member) => member.connectCalls)).toEqual([1, 1, 1])
+
+    at(members, 0).ready()
+    at(members, 2).ready()
+    expect(set.status().readyMembers).toBe(3)
+    expect(set.status().state).toBe("ready")
+    await set.close()
+  })
 
-test("start followed immediately by createConnection returns a socket and waits for readiness", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  assert.equal(socket.connecting, true)
-  assert.equal(socket.gatewayId, undefined)
-  assert.equal(set.status().pendingOpens, 1)
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-
-  at(members, 0).ready()
-  await started
-  assert.equal(gatewayOf(socket), "starlink")
-  assert.deepEqual(members.map((member) => member.opens), [1, 0, 0])
-  await set.close()
-})
+  it("start followed immediately by createConnection returns a socket and waits for readiness", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    expect(socket.connecting).toBe(true)
+    expect(socket.gatewayId).toBe(undefined)
+    expect(set.status().pendingOpens).toBe(1)
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
 
-test("createConnection before start lazily warms the set and waits for minimum readiness", async () => {
-  const {set, members} = fixture({minimumReadyMembers: 2})
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  assert.deepEqual(members.map((member) => member.connectCalls), [1, 1, 1])
-
-  at(members, 0).ready()
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-  at(members, 1).ready()
-  assert.equal(gatewayOf(socket), "starlink")
-  assert.deepEqual(members.map((member) => member.opens), [1, 0, 0])
-  await set.close()
-})
+    at(members, 0).ready()
+    await started
+    expect(gatewayOf(socket)).toBe("starlink")
+    expect(members.map((member) => member.opens)).toEqual([1, 0, 0])
+    await set.close()
+  })
 
-test("pending opens snapshot caller options and nested target at call time", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  const target = {host: "original.internal", port: 443}
-  const openOptions = {
-    host: "original-fallback.internal",
-    port: 80,
-    target,
-    sessionName: "original-session",
-    identifier: "snapshot_stream_01",
-    allowHalfOpen: true,
-    readableHighWaterMark: 7,
-    writableHighWaterMark: 9
-  }
-  const socket = set.createConnection(openOptions)
-
-  openOptions.host = "mutated-fallback.internal"
-  openOptions.port = 81
-  openOptions.sessionName = "mutated-session"
-  openOptions.identifier = "mutated_stream_01"
-  openOptions.allowHalfOpen = false
-  openOptions.readableHighWaterMark = 70
-  openOptions.writableHighWaterMark = 90
-  target.host = "mutated.internal"
-  target.port = 444
-
-  at(members, 0).ready()
-  await started
-  const accepted = at(at(members, 0).createConnectionCalls, 0)
-  assert.deepEqual(accepted, {
-    host: "original-fallback.internal",
-    port: 80,
-    target: {host: "original.internal", port: 443},
-    sessionName: "original-session",
-    identifier: "snapshot_stream_01",
-    allowHalfOpen: true,
-    readableHighWaterMark: 7,
-    writableHighWaterMark: 9
-  })
-  assert.notEqual(accepted, openOptions)
-  assert.notEqual(accepted.target, target)
-  assert.equal(socket.remoteAddress, "original.internal")
-  assert.equal(socket.remotePort, 443)
-  socket.destroy()
-  await set.close()
-})
+  it("createConnection before start lazily warms the set and waits for minimum readiness", async () => {
+    const {set, members} = fixture({minimumReadyMembers: 2})
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    expect(members.map((member) => member.connectCalls)).toEqual([1, 1, 1])
 
-test("pending opens preserve null target fallback to host and port", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  const options = /** @type {import('../../../src/client/multiplexed-connection.js').VirtualConnectionOptions} */ (/** @type {unknown} */ ({
-    target: null,
-    host: "fallback.internal",
-    port: 443,
-    sessionName: "null-target-fallback"
-  }))
-  const socket = set.createConnection(options)
-  assert.equal(socket.remoteAddress, "fallback.internal")
-  assert.equal(socket.remotePort, 443)
-
-  at(members, 0).ready()
-  await started
-  assert.deepEqual(at(at(members, 0).createConnectionCalls, 0), {
-    target: null,
-    host: "fallback.internal",
-    port: 443,
-    sessionName: "null-target-fallback"
-  })
-  socket.destroy()
-  await set.close()
-})
+    at(members, 0).ready()
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+    at(members, 1).ready()
+    expect(gatewayOf(socket)).toBe("starlink")
+    expect(members.map((member) => member.opens)).toEqual([1, 0, 0])
+    await set.close()
+  })
 
-test("round-robins each virtual open fairly across currently ready sticky members", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  members.forEach((member) => member.ready())
-  await started
-
-  const firstThirty = Array.from({length: 30}, () => set.createConnection({host: "target.internal", port: 443}))
-  assert.deepEqual(firstThirty.map(gatewayOf).slice(0, 6), ["starlink", "zyxel", "o2gateway", "starlink", "zyxel", "o2gateway"])
-  assert.deepEqual(set.status().members.map((member) => member.assignments), [10, 10, 10])
-
-  at(members, 1).degrade()
-  const whileDown = Array.from({length: 25}, () => set.createConnection({host: "target.internal", port: 443}))
-  assert.equal(whileDown.every((socket) => gatewayOf(socket) !== "zyxel"), true)
-  const siblingAssignments = set.status().members.filter((member) => member.gatewayId !== "zyxel").map((member) => member.assignments - 10)
-  assert(Math.max(...siblingAssignments) - Math.min(...siblingAssignments) <= 1)
-  assert.equal(gatewayOf(at(firstThirty, 1)), "zyxel")
-
-  at(members, 1).ready()
-  const beforeRecovery = set.status().members.map((member) => member.assignments)
-  const afterRecovery = Array.from({length: 100}, () => set.createConnection({host: "target.internal", port: 443}))
-  assert.equal(afterRecovery.some((socket) => gatewayOf(socket) === "zyxel"), true)
-  const recoveryAssignments = set.status().members.map((member, index) => member.assignments - at(beforeRecovery, index))
-  assert(Math.max(...recoveryAssignments) - Math.min(...recoveryAssignments) <= 1)
-  assert.equal(set.status().virtualOpens, 155)
-  await set.close()
-})
+  it("pending opens snapshot caller options and nested target at call time", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const target = {host: "original.internal", port: 443}
+    const openOptions = {
+      host: "original-fallback.internal",
+      port: 80,
+      target,
+      sessionName: "original-session",
+      identifier: "snapshot_stream_01",
+      allowHalfOpen: true,
+      readableHighWaterMark: 7,
+      writableHighWaterMark: 9
+    }
+    const socket = set.createConnection(openOptions)
+
+    openOptions.host = "mutated-fallback.internal"
+    openOptions.port = 81
+    openOptions.sessionName = "mutated-session"
+    openOptions.identifier = "mutated_stream_01"
+    openOptions.allowHalfOpen = false
+    openOptions.readableHighWaterMark = 70
+    openOptions.writableHighWaterMark = 90
+    target.host = "mutated.internal"
+    target.port = 444
+
+    at(members, 0).ready()
+    await started
+    const accepted = at(at(members, 0).createConnectionCalls, 0)
+    expect(accepted).toEqual({
+      host: "original-fallback.internal",
+      port: 80,
+      target: {host: "original.internal", port: 443},
+      sessionName: "original-session",
+      identifier: "snapshot_stream_01",
+      allowHalfOpen: true,
+      readableHighWaterMark: 7,
+      writableHighWaterMark: 9
+    })
+    expect(accepted).not.toBe(openOptions)
+    expect(accepted.target).not.toBe(target)
+    expect(socket.remoteAddress).toBe("original.internal")
+    expect(socket.remotePort).toBe(443)
+    socket.destroy()
+    await set.close()
+  })
+
+  it("pending opens preserve null target fallback to host and port", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const options = /** @type {import('../../../src/client/multiplexed-connection.js').VirtualConnectionOptions} */ (/** @type {unknown} */ ({
+      target: null,
+      host: "fallback.internal",
+      port: 443,
+      sessionName: "null-target-fallback"
+    }))
+    const socket = set.createConnection(options)
+    expect(socket.remoteAddress).toBe("fallback.internal")
+    expect(socket.remotePort).toBe(443)
+
+    at(members, 0).ready()
+    await started
+    expect(at(at(members, 0).createConnectionCalls, 0)).toEqual({
+      target: null,
+      host: "fallback.internal",
+      port: 443,
+      sessionName: "null-target-fallback"
+    })
+    socket.destroy()
+    await set.close()
+  })
 
-test("25 and 100 continuously healthy opens have exact deterministic distributions", async () => {
-  for (const [count, expected] of /** @type {Array<[number, number[]]>} */ ([[25, [9, 8, 8]], [100, [34, 33, 33]]])) {
+  it("round-robins each virtual open fairly across currently ready sticky members", async () => {
     const {set, members} = fixture()
     const started = set.start()
     members.forEach((member) => member.ready())
     await started
-    Array.from({length: count}, () => set.createConnection({host: "target.internal", port: 443}))
-    assert.deepEqual(set.status().members.map((member) => member.assignments), expected)
-    assert.deepEqual(members.map((member) => member.opens), expected)
+
+    const firstThirty = Array.from({length: 30}, () => set.createConnection({host: "target.internal", port: 443}))
+    expect(firstThirty.map(gatewayOf).slice(0, 6)).toEqual(["starlink", "zyxel", "o2gateway", "starlink", "zyxel", "o2gateway"])
+    expect(set.status().members.map((member) => member.assignments)).toEqual([10, 10, 10])
+
+    at(members, 1).degrade()
+    const whileDown = Array.from({length: 25}, () => set.createConnection({host: "target.internal", port: 443}))
+    expect(whileDown.every((socket) => gatewayOf(socket) !== "zyxel")).toBe(true)
+    const siblingAssignments = set.status().members.filter((member) => member.gatewayId !== "zyxel").map((member) => member.assignments - 10)
+    expect(Math.max(...siblingAssignments) - Math.min(...siblingAssignments) <= 1).toBeTruthy()
+    expect(gatewayOf(at(firstThirty, 1))).toBe("zyxel")
+
+    at(members, 1).ready()
+    const beforeRecovery = set.status().members.map((member) => member.assignments)
+    const afterRecovery = Array.from({length: 100}, () => set.createConnection({host: "target.internal", port: 443}))
+    expect(afterRecovery.some((socket) => gatewayOf(socket) === "zyxel")).toBe(true)
+    const recoveryAssignments = set.status().members.map((member, index) => member.assignments - at(beforeRecovery, index))
+    expect(Math.max(...recoveryAssignments) - Math.min(...recoveryAssignments) <= 1).toBeTruthy()
+    expect(set.status().virtualOpens).toBe(155)
     await set.close()
-  }
-})
+  })
 
-test("all-members reconnecting queues FIFO opens until one ready member recovers", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  members.forEach((member) => member.ready())
-  await started
-  members.forEach((member) => member.degrade())
-  /** @type {string[]} */
-  const callbackOrder = []
-  const sockets = ["first", "second", "third"].map((sessionName) => set.createConnection({host: "target.internal", port: 443, sessionName}, (error) => {
-    assert.equal(error, null)
-    callbackOrder.push(sessionName)
-  }))
-  assert.equal(sockets.every((socket) => socket.gatewayId === undefined), true)
-  assert.equal(set.status().pendingOpens, 3)
-  assert.equal(set.status().virtualOpens, 0)
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-
-  at(members, 1).ready()
-  await new Promise((resolve) => setImmediate(resolve))
-  assert.deepEqual(callbackOrder, ["first", "second", "third"])
-  assert.equal(sockets.every((socket) => socket.gatewayId === "zyxel"), true)
-  assert.deepEqual(at(members, 1).createConnectionCalls.map((call) => call.sessionName), ["first", "second", "third"])
-  assert.equal(set.status().pendingOpens, 0)
-  assert.equal(set.status().virtualOpens, 3)
-  await set.close()
-})
+  it("25 and 100 continuously healthy opens have exact deterministic distributions", async () => {
+    for (const [count, expected] of /** @type {Array<[number, number[]]>} */ ([[25, [9, 8, 8]], [100, [34, 33, 33]]])) {
+      const {set, members} = fixture()
+      const started = set.start()
+      members.forEach((member) => member.ready())
+      await started
+      Array.from({length: count}, () => set.createConnection({host: "target.internal", port: 443}))
+      expect(set.status().members.map((member) => member.assignments)).toEqual(expected)
+      expect(members.map((member) => member.opens)).toEqual(expected)
+      await set.close()
+    }
+  })
 
-test("transient reverse-hub codes keep opens pending until a member reconnects", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  members.forEach((member) => member.ready())
-  await started
-  const transientCodes = ["GATEWAY_UNAVAILABLE", "GATEWAY_DISCONNECTED", "GATEWAY_REPLACED", "HUB_SHUTDOWN"]
-  members.forEach((member, index) => member.degrade(Object.assign(new Error("transient reverse route"), {code: at(transientCodes, index)})))
-  at(members, 0).setState("reconnecting", Object.assign(new Error("transient hub shutdown"), {code: at(transientCodes, 3)}))
-  let callbacks = 0
-  const socket = set.createConnection({host: "target.internal", port: 443}, (error) => {
-    assert.equal(error, null)
-    callbacks += 1
-  })
-  const ready = onceEvent(socket, "ready")
-  await new Promise((resolve) => setImmediate(resolve))
-  assert.equal(callbacks, 0)
-  assert.equal(set.status().state, "degraded")
-  assert.equal(set.status().pendingOpens, 1)
-  assert.deepEqual(set.status().members.map((member) => member.terminalErrorCode), [null, null, null])
-  at(members, 1).ready()
-  await ready
-  assert.equal(callbacks, 1)
-  assert.equal(socket.gatewayId, "zyxel")
-  await set.close()
-})
+  it("opens skip a ready member whose gateway the hub reported unavailable", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    at(members, 0).gatewayUnavailable = true
+    for (let offset = 0; offset < 12; offset += 1) {
+      const socket = set.createConnection({host: "target.internal", port: 443})
+      expect(gatewayOf(socket) === "starlink").toBe(false)
+    }
+    expect(set.status().members.map((member) => member.assignments)).toEqual([0, 6, 6])
+    at(members, 0).gatewayUnavailable = false
+    const recovered = set.createConnection({host: "target.internal", port: 443})
+    expect(gatewayOf(recovered)).toBe("starlink")
+    await set.close()
+  })
 
-test("pending assignment preserves callback, connect, ready, and immutable gateway ordering", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  /** @type {string[]} */
-  const events = []
-  let callbacks = 0
-  const socket = set.createConnection({host: "target.internal", port: 443}, (error, callbackSocket) => {
-    callbacks += 1
-    assert.equal(error, null)
-    assert.equal(callbackSocket, socket)
-    events.push("callback")
-  })
-  socket.on("connect", () => events.push("connect"))
-  socket.on("ready", () => events.push("ready"))
-  const ready = onceEvent(socket, "ready")
-  at(members, 0).ready()
-  await started
-  await ready
-  assert.deepEqual(events, ["callback", "connect", "ready"])
-  assert.equal(callbacks, 1)
-  assert.equal(socket.gatewayId, "starlink")
-  const descriptor = Object.getOwnPropertyDescriptor(socket, "gatewayId")
-  assert.equal(descriptor?.set, undefined)
-  assert.equal(descriptor?.configurable, false)
-  at(members, 0).degrade()
-  at(members, 1).ready()
-  assert.equal(socket.gatewayId, "starlink")
-  await set.close()
-})
+  it("a stale gateway-unavailable mark cannot wedge the set when every ready member is marked", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    members.forEach((member) => { member.gatewayUnavailable = true })
+    const socket = set.createConnection({host: "target.internal", port: 443}, (error) => {
+      expect(error).toBe(null)
+    })
+    expect(socket.gatewayId !== undefined).toBe(true)
+    expect(set.status().pendingOpens).toBe(0)
+    await set.close()
+  })
 
-test("destroy before assignment cancels the pending open and cannot leak a later member stream", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  const closed = onceEvent(socket, "close")
-  socket.destroy()
-  await closed
-  assert.equal(set.status().pendingOpens, 0)
-  at(members, 0).ready()
-  await started
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-  await set.close()
-})
+  it("all-members reconnecting queues FIFO opens until one ready member recovers", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    members.forEach((member) => member.degrade())
+    /** @type {string[]} */
+    const callbackOrder = []
+    const sockets = ["first", "second", "third"].map((sessionName) => set.createConnection({host: "target.internal", port: 443, sessionName}, (error) => {
+      expect(error).toBe(null)
+      callbackOrder.push(sessionName)
+    }))
+    expect(sockets.every((socket) => socket.gatewayId === undefined)).toBe(true)
+    expect(set.status().pendingOpens).toBe(3)
+    expect(set.status().virtualOpens).toBe(0)
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+
+    at(members, 1).ready()
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(callbackOrder).toEqual(["first", "second", "third"])
+    expect(sockets.every((socket) => socket.gatewayId === "zyxel")).toBe(true)
+    expect(at(members, 1).createConnectionCalls.map((call) => call.sessionName)).toEqual(["first", "second", "third"])
+    expect(set.status().pendingOpens).toBe(0)
+    expect(set.status().virtualOpens).toBe(3)
+    await set.close()
+  })
 
-test("terminal startup failure reaches start and each pending socket exactly once", async () => {
-  const {set, members} = fixture()
-  const start = set.start()
-  let callbacks = 0
-  /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
-  let pendingSocket
-  const callbackResult = new Promise((resolve) => {
-    pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => {
+  it("transient reverse-hub codes keep opens pending until a member reconnects", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    const transientCodes = ["GATEWAY_UNAVAILABLE", "GATEWAY_DISCONNECTED", "GATEWAY_REPLACED", "HUB_SHUTDOWN"]
+    members.forEach((member, index) => member.degrade(Object.assign(new Error("transient reverse route"), {code: at(transientCodes, index)})))
+    at(members, 0).setState("reconnecting", Object.assign(new Error("transient hub shutdown"), {code: at(transientCodes, 3)}))
+    let callbacks = 0
+    const socket = set.createConnection({host: "target.internal", port: 443}, (error) => {
+      expect(error).toBe(null)
       callbacks += 1
-      resolve({error, socket})
     })
+    const ready = onceEvent(socket, "ready")
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(callbacks).toBe(0)
+    expect(set.status().state).toBe("degraded")
+    expect(set.status().pendingOpens).toBe(1)
+    expect(set.status().members.map((member) => member.terminalErrorCode)).toEqual([null, null, null])
+    at(members, 1).ready()
+    await ready
+    expect(callbacks).toBe(1)
+    expect(socket.gatewayId).toBe("zyxel")
+    await set.close()
   })
-  assert(pendingSocket !== undefined)
-  const closed = onceEvent(pendingSocket, "close")
-  const failures = members.map((member) => new Error(`${member.gatewayId} unavailable`))
-  members.forEach((member, index) => member.fail(at(failures, index)))
-  await assert.rejects(start, (error) => error instanceof AggregateError && error.errors.length === 3)
-  const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
-  await closed
-  assert(result.error instanceof AggregateError)
-  assert.equal(callbacks, 1)
-  assert.equal(set.status().state, "failed")
-  assert.equal(set.status().pendingOpens, 0)
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-  await set.close()
-})
 
-test("terminal loss preserves ordered member causes for pending and future opens", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  members.forEach((member) => member.ready())
-  await started
-  members.forEach((member) => member.degrade())
-
-  /** @type {Error | undefined} */
-  let pendingError
-  const pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error) => { pendingError = error ?? undefined })
-  const pendingClosed = onceEvent(pendingSocket, "close")
-  const causes = [
-    Object.assign(new Error("starlink certificate rejected"), {code: "ERR_TLS_CERT_ALTNAME_INVALID"}),
-    Object.assign(new Error("zyxel authentication rejected"), {code: "AUTH_REQUIRED"}),
-    Object.assign(new Error("o2 protocol rejected"), {code: "PROTOCOL_MISMATCH"})
-  ]
-  members.forEach((member, index) => member.fail(at(causes, index)))
-  await pendingClosed
-  assert(pendingError instanceof SocketductTransportSetTerminalError)
-  assert.equal(/** @type {{code?: string}} */ (pendingError).code, "SOCKETDUCT_TRANSPORT_SET_TERMINAL")
-  assert.deepEqual(pendingError.errors, causes)
-  const status = set.status()
-  assert.deepEqual(status.members.map((member) => member.terminalErrorCode), causes.map((error) => error.code))
-  assert.doesNotMatch(JSON.stringify(status), /certificate rejected|authentication rejected|protocol rejected/)
-  assert.equal(status.state, "failed")
-
-  let callbacks = 0
-  /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
-  let failedSocket
-  const callbackResult = new Promise((resolve) => {
-    failedSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => {
+  it("pending assignment preserves callback, connect, ready, and immutable gateway ordering", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    /** @type {string[]} */
+    const events = []
+    let callbacks = 0
+    const socket = set.createConnection({host: "target.internal", port: 443}, (error, callbackSocket) => {
       callbacks += 1
-      resolve({error, socket})
+      expect(error).toBe(null)
+      expect(callbackSocket).toBe(socket)
+      events.push("callback")
     })
+    socket.on("connect", () => events.push("connect"))
+    socket.on("ready", () => events.push("ready"))
+    const ready = onceEvent(socket, "ready")
+    at(members, 0).ready()
+    await started
+    await ready
+    expect(events).toEqual(["callback", "connect", "ready"])
+    expect(callbacks).toBe(1)
+    expect(socket.gatewayId).toBe("starlink")
+    const descriptor = Object.getOwnPropertyDescriptor(socket, "gatewayId")
+    expect(descriptor?.set).toBe(undefined)
+    expect(descriptor?.configurable).toBe(false)
+    at(members, 0).degrade()
+    at(members, 1).ready()
+    expect(socket.gatewayId).toBe("starlink")
+    await set.close()
   })
-  assert(failedSocket !== undefined)
-  const closed = onceEvent(failedSocket, "close")
-  const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
-  await closed
-  assert.equal(result.error, pendingError)
-  assert.equal(callbacks, 1)
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-  await set.close()
-})
 
-test("close fails a pending socket without allocating a member and rejects later opens", async () => {
-  const {set, members} = fixture()
-  const start = set.start()
-  /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
-  let pendingSocket
-  const callbackResult = new Promise((resolve) => {
-    pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => resolve({error, socket}))
-  })
-  assert(pendingSocket !== undefined)
-  const closed = onceEvent(pendingSocket, "close")
-  const close = set.close()
-  await assert.rejects(start, (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_TRANSPORT_SET_CLOSED")
-  const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
-  await closed
-  assert.equal(/** @type {{code?: string}} */ (result.error).code, "SOCKETDUCT_TRANSPORT_SET_CLOSED")
-  await close
-  assert.deepEqual(members.map((member) => member.opens), [0, 0, 0])
-  assert.throws(() => set.createConnection({host: "target.internal", port: 443}), /closed/i)
-})
+  it("destroy before assignment cancels the pending open and cannot leak a later member stream", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    const closed = onceEvent(socket, "close")
+    socket.destroy()
+    await closed
+    expect(set.status().pendingOpens).toBe(0)
+    at(members, 0).ready()
+    await started
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+    await set.close()
+  })
 
-test("bounds pending open count and pending application bytes", async () => {
-  const countFixture = fixture({maxPendingOpens: 1})
-  const first = countFixture.set.createConnection({host: "target.internal", port: 443})
-  assert.throws(
-    () => countFixture.set.createConnection({host: "target.internal", port: 443}),
-    (error) => error instanceof SocketductTransportSetLimitError && error.code === "SOCKETDUCT_SET_PENDING_OPEN_LIMIT"
-  )
-  const firstClosed = onceEvent(first, "close")
-  first.destroy()
-  await firstClosed
-  await countFixture.set.close()
-
-  const byteFixture = fixture({maxTotalBufferBytes: 4, maxTotalQueuedBytes: 4})
-  const socket = byteFixture.set.createConnection({host: "target.internal", port: 443})
-  const streamError = onceEvent(socket, "error")
-  const socketClosed = onceEvent(socket, "close")
-  socket.write("four")
-  const callbackError = new Promise((resolve) => {
-    assert.equal(socket.write("!", (error) => resolve(error)), false)
-  })
-  const [error] = await streamError
-  assert.equal(error, await callbackError)
-  await socketClosed
-  assert.equal(byteFixture.set.status().budgets.dataBytes, 0)
-  assert.equal(byteFixture.set.status().budgets.queuedBytes, 0)
-  await byteFixture.set.close()
-})
+  it("terminal startup failure reaches start and each pending socket exactly once", async () => {
+    const {set, members} = fixture()
+    const start = set.start()
+    let callbacks = 0
+    /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
+    let pendingSocket
+    const callbackResult = new Promise((resolve) => {
+      pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => {
+        callbacks += 1
+        resolve({error, socket})
+      })
+    })
+    expect(pendingSocket).toBeDefined()
+    const closed = onceEvent(/** @type {import("node:events").EventEmitter} */ (pendingSocket), "close")
+    const failures = members.map((member) => new Error(`${member.gatewayId} unavailable`))
+    members.forEach((member, index) => member.fail(at(failures, index)))
+    let startError
+    try {
+      await start
+    } catch (error) {
+      startError = /** @type {Error} */ (error)
+    }
+    expect(startError).toBeInstanceOf(AggregateError)
+    expect(/** @type {AggregateError} */ (startError).errors.length).toBe(3)
+    const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
+    await closed
+    expect(result.error).toBeInstanceOf(AggregateError)
+    expect(/** @type {AggregateError} */ (result.error).errors).toEqual(failures)
+    expect(callbacks).toBe(1)
+    expect(set.status().state).toBe("failed")
+    expect(set.status().pendingOpens).toBe(0)
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+    await set.close()
+  })
 
-test("pending sockets retain timeout and Writable backpressure behavior", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  const socket = set.createConnection({
-    host: "target.internal",
-    port: 443,
-    writableHighWaterMark: 4
-  })
-  const timedOut = onceEvent(socket, "timeout")
-  socket.setTimeout(1)
-  await timedOut
-  assert.equal(socket.destroyed, false)
-  assert.equal(socket.connecting, true)
-  socket.setTimeout(0)
-
-  const drained = onceEvent(socket, "drain")
-  const written = new Promise((resolve, reject) => {
-    assert.equal(socket.write("four", (error) => error ? reject(error) : resolve(undefined)), false)
-  })
-  assert.equal(set.status().budgets.dataBytes, 4)
-  at(members, 0).ready()
-  await Promise.all([started, written, drained])
-  assert.equal(set.status().budgets.dataBytes, 0)
-  socket.destroy()
-  await set.close()
-})
+  it("terminal loss preserves ordered member causes for pending and future opens", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    members.forEach((member) => member.degrade())
+
+    /** @type {Error | undefined} */
+    let pendingError
+    const pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error) => { pendingError = error ?? undefined })
+    const pendingClosed = onceEvent(/** @type {import("node:events").EventEmitter} */ (pendingSocket), "close")
+    const causes = [
+      Object.assign(new Error("starlink certificate rejected"), {code: "ERR_TLS_CERT_ALTNAME_INVALID"}),
+      Object.assign(new Error("zyxel authentication rejected"), {code: "AUTH_REQUIRED"}),
+      Object.assign(new Error("o2 protocol rejected"), {code: "PROTOCOL_MISMATCH"})
+    ]
+    members.forEach((member, index) => member.fail(at(causes, index)))
+    await pendingClosed
+    expect(pendingError).toBeInstanceOf(SocketductTransportSetTerminalError)
+    if (!(pendingError instanceof SocketductTransportSetTerminalError)) throw new Error("expected terminal error")
+    expect(pendingError.code).toBe("SOCKETDUCT_TRANSPORT_SET_TERMINAL")
+    expect(pendingError.errors).toEqual(causes)
+    const status = set.status()
+    expect(status.members.map((member) => member.terminalErrorCode)).toEqual(causes.map((error) => error.code))
+    expect(JSON.stringify(status)).not.toMatch(/certificate rejected|authentication rejected|protocol rejected/)
+    expect(status.state).toBe("failed")
+
+    let callbacks = 0
+    /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
+    let failedSocket
+    const callbackResult = new Promise((resolve) => {
+      failedSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => {
+        callbacks += 1
+        resolve({error, socket})
+      })
+    })
+    expect(failedSocket).toBeDefined()
+    if (failedSocket === undefined) throw new Error("expected failedSocket")
+    const closed = onceEvent(failedSocket, "close")
+    const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
+    await closed
+    expect(result.error).toBe(pendingError)
+    expect(callbacks).toBe(1)
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+    await set.close()
+  })
 
-test("pending sockets reserve and write non-Uint8 typed-array views", async () => {
-  const payload = new Uint16Array([0x1234, 0xabcd])
-  const expected = Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength)
-  const {set, members} = fixture({maxTotalBufferBytes: payload.byteLength, maxTotalQueuedBytes: payload.byteLength})
-  const started = set.start()
-  const socket = set.createConnection({host: "target.internal", port: 443, writableHighWaterMark: payload.byteLength})
-  let callbacks = 0
-  /** @type {(error?: Error | null) => void} */
-  let completeWrite = () => {}
-  const written = new Promise((resolve, reject) => {
-    completeWrite = (error) => {
-      callbacks += 1
-      if (error) reject(error)
-      else resolve(undefined)
+  it("close fails a pending socket without allocating a member and rejects later opens", async () => {
+    const {set, members} = fixture()
+    const start = set.start()
+    /** @type {import('../../../src/client/virtual-socket.js').VirtualSocket | undefined} */
+    let pendingSocket
+    const callbackResult = new Promise((resolve) => {
+      pendingSocket = set.createConnection({host: "target.internal", port: 443}, (error, socket) => resolve({error, socket}))
+    })
+    expect(pendingSocket).toBeDefined()
+    const closed = onceEvent(/** @type {import("node:events").EventEmitter} */ (pendingSocket), "close")
+    const close = set.close()
+    let startError
+    try {
+      await start
+    } catch (error) {
+      startError = /** @type {Error} */ (error)
     }
+    expect(startError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (startError).code).toBe("SOCKETDUCT_TRANSPORT_SET_CLOSED")
+    const result = /** @type {{error: Error, socket: import('../../../src/client/virtual-socket.js').VirtualSocket}} */ (await callbackResult)
+    await closed
+    expect(/** @type {{code?: string}} */ (result.error).code).toBe("SOCKETDUCT_TRANSPORT_SET_CLOSED")
+    await close
+    expect(members.map((member) => member.opens)).toEqual([0, 0, 0])
+    expect(() => set.createConnection({host: "target.internal", port: 443})).toThrow(/closed/i)
   })
-  const drained = onceEvent(socket, "drain")
-
-  assert.equal(socket.write(payload, completeWrite), false)
-  assert.equal(set.status().budgets.dataBytes, payload.byteLength)
-  assert.throws(
-    () => socket.write(/** @type {never} */ ({unsupported: true})),
-    (error) => /** @type {{code?: string}} */ (error).code === "ERR_INVALID_ARG_TYPE"
-  )
-  assert.equal(set.status().budgets.dataBytes, payload.byteLength)
-
-  at(members, 0).ready()
-  await Promise.all([started, written, drained])
-  assert.equal(callbacks, 1)
-  assert.deepEqual(at(at(members, 0).sockets, 0).writes, [expected])
-  assert.equal(set.status().budgets.dataBytes, 0)
-  socket.destroy()
-  await set.close()
-})
 
-test("pending socket end payload reserves and sends bytes after assignment", async () => {
-  const {set, members} = fixture({maxTotalBufferBytes: 5, maxTotalQueuedBytes: 5})
-  const started = set.start()
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  let callbacks = 0
-  /** @type {string[]} */
-  const events = []
-  const finished = new Promise((resolve) => socket.once("finish", () => {
-    events.push("finish")
-    resolve(undefined)
-  }))
-  const ended = new Promise((resolve) => {
-    const returned = socket.end("final", () => {
-      callbacks += 1
-      events.push("callback")
-      resolve(undefined)
+  it("bounds pending open count and pending application bytes", async () => {
+    const countFixture = fixture({maxPendingOpens: 1})
+    const first = countFixture.set.createConnection({host: "target.internal", port: 443})
+    let limitError
+    try {
+      countFixture.set.createConnection({host: "target.internal", port: 443})
+    } catch (error) {
+      limitError = /** @type {Error} */ (error)
+    }
+    expect(limitError).toBeInstanceOf(SocketductTransportSetLimitError)
+    expect(/** @type {{code?: string}} */ (limitError).code).toBe("SOCKETDUCT_SET_PENDING_OPEN_LIMIT")
+    const firstClosed = onceEvent(first, "close")
+    first.destroy()
+    await firstClosed
+    await countFixture.set.close()
+
+    const byteFixture = fixture({maxTotalBufferBytes: 4, maxTotalQueuedBytes: 4})
+    const socket = byteFixture.set.createConnection({host: "target.internal", port: 443})
+    const streamError = onceEvent(socket, "error")
+    const socketClosed = onceEvent(socket, "close")
+    socket.write("four")
+    const callbackError = new Promise((resolve) => {
+      expect(socket.write("!", (error) => resolve(error))).toBe(false)
     })
-    assert.equal(returned, socket)
+    const [error] = await streamError
+    expect(error).toBe(await callbackError)
+    await socketClosed
+    expect(byteFixture.set.status().budgets.dataBytes).toBe(0)
+    expect(byteFixture.set.status().budgets.queuedBytes).toBe(0)
+    await byteFixture.set.close()
   })
 
-  assert.equal(set.status().budgets.dataBytes, 5)
+  it("pending sockets retain timeout and Writable backpressure behavior", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    const socket = set.createConnection({
+      host: "target.internal",
+      port: 443,
+      writableHighWaterMark: 4
+    })
+    const timedOut = onceEvent(socket, "timeout")
+    socket.setTimeout(1)
+    await timedOut
+    expect(socket.destroyed).toBe(false)
+    expect(socket.connecting).toBe(true)
+    socket.setTimeout(0)
+
+    const drained = onceEvent(socket, "drain")
+    const written = new Promise((resolve, reject) => {
+      expect(socket.write("four", (error) => error ? reject(error) : resolve(undefined))).toBe(false)
+    })
+    expect(set.status().budgets.dataBytes).toBe(4)
+    at(members, 0).ready()
+    await Promise.all([started, written, drained])
+    expect(set.status().budgets.dataBytes).toBe(0)
+    socket.destroy()
+    await set.close()
+  })
 
-  at(members, 0).ready()
-  await Promise.all([started, ended, finished])
-  assert.equal(callbacks, 1)
-  assert.deepEqual(events, ["callback", "finish"])
-  assert.deepEqual(at(at(members, 0).sockets, 0).writes, [Buffer.from("final")])
-  assert.equal(set.status().budgets.dataBytes, 0)
-  await set.close()
-})
+  it("pending sockets reserve and write non-Uint8 typed-array views", async () => {
+    const payload = new Uint16Array([0x1234, 0xabcd])
+    const expected = Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength)
+    const {set, members} = fixture({maxTotalBufferBytes: payload.byteLength, maxTotalQueuedBytes: payload.byteLength})
+    const started = set.start()
+    const socket = set.createConnection({host: "target.internal", port: 443, writableHighWaterMark: payload.byteLength})
+    let callbacks = 0
+    /** @type {(error?: Error | null) => void} */
+    let completeWrite = () => {}
+    const written = new Promise((resolve, reject) => {
+      completeWrite = (error) => {
+        callbacks += 1
+        if (error) reject(error)
+        else resolve(undefined)
+      }
+    })
+    const drained = onceEvent(socket, "drain")
+
+    expect(socket.write(payload, completeWrite)).toBe(false)
+    expect(set.status().budgets.dataBytes).toBe(payload.byteLength)
+    let unsupportedError
+    try {
+      socket.write(/** @type {never} */ ({unsupported: true}))
+    } catch (error) {
+      unsupportedError = /** @type {Error} */ (error)
+    }
+    expect(unsupportedError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (unsupportedError).code).toBe("ERR_INVALID_ARG_TYPE")
+    expect(set.status().budgets.dataBytes).toBe(payload.byteLength)
+
+    at(members, 0).ready()
+    await Promise.all([started, written, drained])
+    expect(callbacks).toBe(1)
+    const actualWrites = at(at(members, 0).sockets, 0).writes
+    expect(actualWrites.length).toBe(1)
+    expect(Buffer.from(at(actualWrites, 0)).equals(expected)).toBe(true)
+    expect(set.status().budgets.dataBytes).toBe(0)
+    socket.destroy()
+    await set.close()
+  })
 
-test("pending socket end reserves and sends DataView bytes", async () => {
-  const buffer = new ArrayBuffer(6)
-  const payload = new DataView(buffer, 1, 4)
-  payload.setUint32(0, 0x1234abcd)
-  const expected = Buffer.from(buffer, payload.byteOffset, payload.byteLength)
-  const {set, members} = fixture({maxTotalBufferBytes: payload.byteLength, maxTotalQueuedBytes: payload.byteLength})
-  const started = set.start()
-  const socket = set.createConnection({host: "target.internal", port: 443})
-  let callbacks = 0
-  /** @type {() => void} */
-  let completeEnd = () => {}
-  const ended = new Promise((resolve) => {
-    completeEnd = () => {
-      callbacks += 1
+  it("pending socket end payload reserves and sends bytes after assignment", async () => {
+    const {set, members} = fixture({maxTotalBufferBytes: 5, maxTotalQueuedBytes: 5})
+    const started = set.start()
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    let callbacks = 0
+    /** @type {string[]} */
+    const events = []
+    const finished = new Promise((resolve) => socket.once("finish", () => {
+      events.push("finish")
       resolve(undefined)
-    }
+    }))
+    const ended = new Promise((resolve) => {
+      const returned = socket.end("final", () => {
+        callbacks += 1
+        events.push("callback")
+        resolve(undefined)
+      })
+      expect(returned).toBe(socket)
+    })
+
+    expect(set.status().budgets.dataBytes).toBe(5)
+
+    at(members, 0).ready()
+    await Promise.all([started, ended, finished])
+    expect(callbacks).toBe(1)
+    expect(events).toEqual(["callback", "finish"])
+    const actualWrites = at(at(members, 0).sockets, 0).writes
+    expect(actualWrites.length).toBe(1)
+    expect(Buffer.from(at(actualWrites, 0)).equals(Buffer.from("final"))).toBe(true)
+    expect(set.status().budgets.dataBytes).toBe(0)
+    await set.close()
   })
 
-  assert.equal(socket.end(payload, completeEnd), socket)
-  assert.equal(set.status().budgets.dataBytes, payload.byteLength)
+  it("pending socket end reserves and sends DataView bytes", async () => {
+    const buffer = new ArrayBuffer(6)
+    const payload = new DataView(buffer, 1, 4)
+    payload.setUint32(0, 0x1234abcd)
+    const expected = Buffer.from(buffer, payload.byteOffset, payload.byteLength)
+    const {set, members} = fixture({maxTotalBufferBytes: payload.byteLength, maxTotalQueuedBytes: payload.byteLength})
+    const started = set.start()
+    const socket = set.createConnection({host: "target.internal", port: 443})
+    let callbacks = 0
+    /** @type {() => void} */
+    let completeEnd = () => {}
+    const ended = new Promise((resolve) => {
+      completeEnd = () => {
+        callbacks += 1
+        resolve(undefined)
+      }
+    })
 
-  at(members, 0).ready()
-  await Promise.all([started, ended])
-  assert.equal(callbacks, 1)
-  assert.deepEqual(at(at(members, 0).sockets, 0).writes, [expected])
-  assert.equal(set.status().budgets.dataBytes, 0)
-  await set.close()
-})
+    expect(socket.end(payload, completeEnd)).toBe(socket)
+    expect(set.status().budgets.dataBytes).toBe(payload.byteLength)
 
-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"}))), (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)
-  assert.throws(() => set.createTlsConnection({gatewayId: "zyxel", host: "target.internal", port: 443}), /recoverConnection/i)
-
-  const recovered = set.recoverConnection({
-    gatewayId: "zyxel",
-    host: "target.internal",
-    port: 443,
-    identifier: "stable_stream_01",
-    sessionName: "durable"
-  })
-  await new Promise((resolve) => setImmediate(resolve))
-  const recoveredLater = set.recoverConnection({
-    gatewayId: "zyxel",
-    host: "target.internal",
-    port: 443,
-    identifier: "stable_stream_02",
-    sessionName: "durable-later"
-  })
-  assert.equal(gatewayOf(recovered), "zyxel")
-  assert.equal(gatewayOf(recoveredLater), "zyxel")
-  assert.deepEqual(members.map((member) => member.opens), [0, 2, 0])
-  assert.equal(at(members, 1).options.connectionId === undefined, false)
-  assert.equal(at(members, 1).createConnectionCalls.length, 0)
-  assert.equal(/** @type {{recover?: unknown}} */ (at(members, 1).recoveryConnectionCalls[0]).recover, true)
-  assert.equal(at(members, 1).recoveryConnectionCalls.length, 2)
-  assert.equal(Object.hasOwn(/** @type {object} */ (at(members, 1).recoveryConnectionCalls[0]), "gatewayId"), false)
-
-  const starting = set.start()
-  assert.throws(() => set.recoverConnection({gatewayId: "zyxel", host: "target.internal", port: 443, identifier: "stable_stream_04"}), /before start/i)
-  members.forEach((member) => member.ready())
-  await starting
-  await set.close()
-})
+    at(members, 0).ready()
+    await Promise.all([started, ended])
+    expect(callbacks).toBe(1)
+    const actualWrites = at(at(members, 0).sockets, 0).writes
+    expect(actualWrites.length).toBe(1)
+    expect(Buffer.from(at(actualWrites, 0)).equals(expected)).toBe(true)
+    expect(set.status().budgets.dataBytes).toBe(0)
+    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()
-})
+  it("recovery requires one original configured selector and registration before start", async () => {
+    const {set, members} = fixture()
+    let notFoundError
+    try {
+      set.recoverConnection(/** @type {Parameters<MultiplexedSocketductTransportSet["recoverConnection"]>[0]} */ (/** @type {unknown} */ ({host: "target.internal", port: 443, identifier: "stable_stream_01"})))
+    } catch (error) {
+      notFoundError = /** @type {Error} */ (error)
+    }
+    expect(notFoundError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (notFoundError).code).toBe("SOCKETDUCT_RECOVERY_NOT_FOUND")
+    expect(() => set.recoverConnection({gatewayId: "unknown", host: "target.internal", port: 443, identifier: "stable_stream_01"})).toThrow(/unknown gatewayId/i)
+    expect(() => set.createConnection(/** @type {import('../../../src/client/multiplexed-connection.js').VirtualConnectionOptions} */ (/** @type {unknown} */ ({gatewayId: "zyxel", host: "target.internal", port: 443})))).toThrow(/recoverConnection/i)
+    expect(() => set.createConnection({recover: true, host: "target.internal", port: 443, identifier: "stable_stream_01"})).toThrow(/recoverConnection/i)
+    expect(() => set.createTlsConnection({gatewayId: "zyxel", host: "target.internal", port: 443})).toThrow(/recoverConnection/i)
+
+    const recovered = set.recoverConnection({
+      gatewayId: "zyxel",
+      host: "target.internal",
+      port: 443,
+      identifier: "stable_stream_01",
+      sessionName: "durable"
+    })
+    await new Promise((resolve) => setImmediate(resolve))
+    const recoveredLater = set.recoverConnection({
+      gatewayId: "zyxel",
+      host: "target.internal",
+      port: 443,
+      identifier: "stable_stream_02",
+      sessionName: "durable-later"
+    })
+    expect(gatewayOf(recovered)).toBe("zyxel")
+    expect(gatewayOf(recoveredLater)).toBe("zyxel")
+    expect(members.map((member) => member.opens)).toEqual([0, 2, 0])
+    expect(at(members, 1).options.connectionId === undefined).toBe(false)
+    expect(at(members, 1).createConnectionCalls.length).toBe(0)
+    expect(/** @type {{recover?: unknown}} */ (at(members, 1).recoveryConnectionCalls[0]).recover).toBe(true)
+    expect(at(members, 1).recoveryConnectionCalls.length).toBe(2)
+    expect(Object.hasOwn(/** @type {object} */ (at(members, 1).recoveryConnectionCalls[0]), "gatewayId")).toBe(false)
+
+    const starting = set.start()
+    expect(() => set.recoverConnection({gatewayId: "zyxel", host: "target.internal", port: 443, identifier: "stable_stream_04"})).toThrow(/before start/i)
+    members.forEach((member) => member.ready())
+    await starting
+    await set.close()
+  })
 
-test("returns the stable selected gatewayId on ordinary and recovered sockets", async () => {
-  const {set, members} = fixture()
-  const started = set.start()
-  members.forEach((member) => member.ready())
-  await started
-  const ordinary = set.createConnection({host: "target.internal", port: 443})
-  assert.equal(gatewayOf(ordinary), "starlink")
-  const descriptor = Object.getOwnPropertyDescriptor(ordinary, "gatewayId")
-  assert.equal(descriptor?.writable, false)
-  await set.close()
-
-  const recoveryFixture = fixture()
-  const recovered = recoveryFixture.set.recoverConnection({gatewayId: "zyxel", host: "target.internal", port: 443, identifier: "stable_stream_03"})
-  assert.equal(gatewayOf(recovered), "zyxel")
-  await recoveryFixture.set.close()
-})
+  it("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
+    })
 
-test("shares aggregate data, spool, and queued-byte reservations across members", async () => {
-  const {set, members} = fixture({maxTotalBufferBytes: 10, maxTotalSpoolBytes: 8, maxTotalQueuedBytes: 12})
-  const budgets = members.map((member) => {
-    const budget = member.options.aggregateBudget
-    assert(budget !== undefined)
-    return budget
-  })
-  assert.equal(new Set(budgets).size, 1)
-  at(budgets, 0).reserveData(6)
-  assert.throws(() => at(budgets, 1).reserveData(3), (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_SET_SPOOL_LIMIT")
-  at(budgets, 2).reserveControl(6)
-  assert.throws(() => at(budgets, 1).reserveControl(1), (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_SET_QUEUE_LIMIT")
-  assert.deepEqual(set.status().budgets, {
-    dataBytes: 6,
-    spoolBytes: 6,
-    queuedBytes: 12,
-    maxDataBytes: 10,
-    maxSpoolBytes: 8,
-    maxQueuedBytes: 12
-  })
-  at(budgets, 0).releaseMemory(6)
-  at(budgets, 0).releaseSpool(6)
-  at(budgets, 2).releaseControl(6)
-  await set.close()
-})
+    const recovered = unique.set.recoverConnection({identifier: "stable_stream_05"})
+    expect(gatewayOf(recovered)).toBe("zyxel")
+    expect(at(unique.members, 1).recoveryConnectionCalls).toEqual([{
+      identifier: "stable_stream_05",
+      target: {host: "target.internal", port: 443},
+      sessionName: "durable-request",
+      manualReceiveAck: true,
+      recover: true
+    }])
+    let missingError
+    try {
+      unique.set.recoverConnection({identifier: "missing_stream_01"})
+    } catch (error) {
+      missingError = /** @type {Error} */ (error)
+    }
+    expect(missingError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (missingError).code).toBe("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)
+    let ambiguousError
+    try {
+      ambiguous.set.recoverConnection({identifier: descriptor.identifier})
+    } catch (error) {
+      ambiguousError = /** @type {Error} */ (error)
+    }
+    expect(ambiguousError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (ambiguousError).code).toBe("SOCKETDUCT_RECOVERY_AMBIGUOUS")
+    await ambiguous.set.close()
+  })
+
+  it("returns the stable selected gatewayId on ordinary and recovered sockets", async () => {
+    const {set, members} = fixture()
+    const started = set.start()
+    members.forEach((member) => member.ready())
+    await started
+    const ordinary = set.createConnection({host: "target.internal", port: 443})
+    expect(gatewayOf(ordinary)).toBe("starlink")
+    const descriptor = Object.getOwnPropertyDescriptor(ordinary, "gatewayId")
+    expect(descriptor?.writable).toBe(false)
+    await set.close()
+
+    const recoveryFixture = fixture()
+    const recovered = recoveryFixture.set.recoverConnection({gatewayId: "zyxel", host: "target.internal", port: 443, identifier: "stable_stream_03"})
+    expect(gatewayOf(recovered)).toBe("zyxel")
+    await recoveryFixture.set.close()
+  })
+
+  it("shares aggregate data, spool, and queued-byte reservations across members", async () => {
+    const {set, members} = fixture({maxTotalBufferBytes: 10, maxTotalSpoolBytes: 8, maxTotalQueuedBytes: 12})
+    const budgets = members.map((member) => {
+      const budget = member.options.aggregateBudget
+      expect(budget).toBeDefined()
+      return /** @type {NonNullable<typeof budget>} */ (budget)
+    })
+    expect(new Set(budgets).size).toBe(1)
+    at(budgets, 0).reserveData(6)
+    let spoolLimitError
+    try {
+      at(budgets, 1).reserveData(3)
+    } catch (error) {
+      spoolLimitError = /** @type {Error} */ (error)
+    }
+    expect(spoolLimitError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (spoolLimitError).code).toBe("SOCKETDUCT_SET_SPOOL_LIMIT")
+    at(budgets, 2).reserveControl(6)
+    let queueLimitError
+    try {
+      at(budgets, 1).reserveControl(1)
+    } catch (error) {
+      queueLimitError = /** @type {Error} */ (error)
+    }
+    expect(queueLimitError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (queueLimitError).code).toBe("SOCKETDUCT_SET_QUEUE_LIMIT")
+    expect(set.status().budgets).toEqual({
+      dataBytes: 6,
+      spoolBytes: 6,
+      queuedBytes: 12,
+      maxDataBytes: 10,
+      maxSpoolBytes: 8,
+      maxQueuedBytes: 12
+    })
+    at(budgets, 0).releaseMemory(6)
+    at(budgets, 0).releaseSpool(6)
+    at(budgets, 2).releaseControl(6)
+    await set.close()
+  })
 
-test("close during startup cannot resurrect members and concurrent close is ordered", async () => {
-  const firstError = new Error("starlink close")
-  const thirdError = new Error("o2 close")
-  const {set, members} = fixture({}, {starlink: firstError, o2gateway: thirdError})
-  const start = set.start()
-  const firstClose = set.close()
-  const secondClose = set.close()
-  assert.equal(firstClose, secondClose)
-  await assert.rejects(start, (error) => /** @type {{code?: string}} */ (error).code === "SOCKETDUCT_TRANSPORT_SET_CLOSED")
-  await assert.rejects(firstClose, (error) => {
-    assert(error instanceof AggregateError)
-    assert.deepEqual(error.errors, [firstError, thirdError])
-    return true
-  })
-  assert.deepEqual(members.map((member) => member.closeCalls), [1, 1, 1])
-  members.forEach((member) => member.ready())
-  assert.equal(set.status().state, "closed")
-  assert.throws(() => set.createConnection({host: "target.internal", port: 443}), /closed/i)
+  it("close during startup cannot resurrect members and concurrent close is ordered", async () => {
+    const firstError = new Error("starlink close")
+    const thirdError = new Error("o2 close")
+    const {set, members} = fixture({}, {starlink: firstError, o2gateway: thirdError})
+    const start = set.start()
+    const firstClose = set.close()
+    const secondClose = set.close()
+    expect(firstClose).toBe(secondClose)
+    let startError
+    try {
+      await start
+    } catch (error) {
+      startError = /** @type {Error} */ (error)
+    }
+    expect(startError).toBeInstanceOf(Error)
+    expect(/** @type {{code?: string}} */ (startError).code).toBe("SOCKETDUCT_TRANSPORT_SET_CLOSED")
+    let closeError
+    try {
+      await firstClose
+    } catch (error) {
+      closeError = /** @type {Error} */ (error)
+    }
+    expect(closeError).toBeInstanceOf(AggregateError)
+    expect(/** @type {AggregateError} */ (closeError).errors).toEqual([firstError, thirdError])
+    expect(members.map((member) => member.closeCalls)).toEqual([1, 1, 1])
+    members.forEach((member) => member.ready())
+    expect(set.status().state).toBe("closed")
+    expect(() => set.createConnection({host: "target.internal", port: 443})).toThrow(/closed/i)
+  })
 })