socketduct 0.1.24 → 0.1.26

package/test/unit/protocol/v3-compression.test.js

@@ -1,31 +1,29 @@
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, it} from "@velocious/testing"
 
 import {ZSTD_CODEC, zstdAvailable} from "../../../src/protocol/compression.js"
 import {AdaptiveCompressor, decodeV3Data, encodeV3Data} from "../../../src/protocol/v3-compression.js"
 import {V3FrameFlag} from "../../../src/protocol/v3-frame.js"
 
-test("v3 reverse DATA compression is independent, bounded, and negotiated", async (t) => {
-  if (!zstdAvailable()) {
-    t.skip("Node runtime has no zstd binding")
-    return
-  }
-  const raw = Buffer.from(Array.from({length: 4096}, (_, index) => `{"dockerEvent":${index},"status":"running"}\n`).join(""))
-  const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
-  assert.equal(encoded.flags, V3FrameFlag.DATA_COMPRESSED)
-  assert(encoded.wireBytes < encoded.rawBytes)
-  assert.deepEqual(await decodeV3Data(encoded, ZSTD_CODEC), raw)
-  await assert.rejects(decodeV3Data(encoded, undefined), /not negotiated/i)
+describe("v3 DATA compression", () => {
+  it("v3 reverse DATA compression is independent, bounded, and negotiated", {skip: !zstdAvailable()}, async () => {
+    // Skipped when the Node runtime has no zstd binding.
+    const raw = Buffer.from(Array.from({length: 4096}, (_, index) => `{"dockerEvent":${index},"status":"running"}\n`).join(""))
+    const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
+    expect(encoded.flags).toBe(V3FrameFlag.DATA_COMPRESSED)
+    expect(encoded.wireBytes < encoded.rawBytes).toBeTruthy()
+    expect(Buffer.from(await decodeV3Data(encoded, ZSTD_CODEC)).equals(Buffer.from(raw))).toBe(true)
+    await expect(decodeV3Data(encoded, undefined)).rejects.toThrow(/not negotiated/i)
 
-  const corrupt = {...encoded, payload: Buffer.from(encoded.payload)}
-  const last = corrupt.payload.length - 1
-  corrupt.payload[last] = /** @type {number} */ (corrupt.payload[last]) ^ 0xff
-  await assert.rejects(decodeV3Data(corrupt, ZSTD_CODEC), /decompress/i)
-})
+    const corrupt = {...encoded, payload: Buffer.from(encoded.payload)}
+    const last = corrupt.payload.length - 1
+    corrupt.payload[last] = /** @type {number} */ (corrupt.payload[last]) ^ 0xff
+    await expect(decodeV3Data(corrupt, ZSTD_CODEC)).rejects.toThrow(/decompress/i)
+  })
 
-test("v3 reverse DATA remains raw when adaptive compression cannot save bytes", async () => {
-  const raw = Buffer.from("small")
-  const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
-  assert.equal(encoded.flags, 0)
-  assert.deepEqual(await decodeV3Data(encoded, ZSTD_CODEC), raw)
+  it("v3 reverse DATA remains raw when adaptive compression cannot save bytes", async () => {
+    const raw = Buffer.from("small")
+    const encoded = await encodeV3Data(raw, ZSTD_CODEC, new AdaptiveCompressor())
+    expect(encoded.flags).toBe(0)
+    expect(Buffer.from(await decodeV3Data(encoded, ZSTD_CODEC)).equals(Buffer.from(raw))).toBe(true)
+  })
 })

package/test/unit/protocol/v3-frame.test.js

@@ -1,5 +1,4 @@
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, it} from "@velocious/testing"
 
 import {
   decodeV3Control,
@@ -10,48 +9,50 @@ import {
   V3FrameType
 } from "../../../src/protocol/v3-frame.js"
 
-test("v3 decoder parses fragmented and coalesced binary frames", () => {
-  const first = encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 7})
-  const second = encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc"))
-  const wire = Buffer.concat([first, second])
-  const decoder = new V3FrameDecoder({maxFrameBytes: 64})
+describe("v3 frame protocol", () => {
+  it("v3 decoder parses fragmented and coalesced binary frames", () => {
+    const first = encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 7})
+    const second = encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc"))
+    const wire = Buffer.concat([first, second])
+    const decoder = new V3FrameDecoder({maxFrameBytes: 64})
 
-  assert.deepEqual(decoder.push(wire.subarray(0, 9)), [])
-  const frames = decoder.push(wire.subarray(9))
-  assert.deepEqual(frames, [
-    {type: V3FrameType.PING, flags: 0, streamId: 0, sequence: 7, payload: Buffer.alloc(0)},
-    {type: V3FrameType.DATA, flags: 0, streamId: 1, sequence: 3, payload: Buffer.from("abc")}
-  ])
-})
+    expect(decoder.push(wire.subarray(0, 9))).toEqual([])
+    const frames = decoder.push(wire.subarray(9))
+    const [pingFrame, dataFrame] = frames
+    expect(pingFrame?.type).toBe(V3FrameType.PING)
+    expect(pingFrame?.flags).toBe(0)
+    expect(pingFrame?.streamId).toBe(0)
+    expect(pingFrame?.sequence).toBe(7)
+    if (!pingFrame) throw new Error("expected a decoded v3 PING frame")
+    expect(Buffer.from(pingFrame.payload).toString("hex")).toBe(Buffer.alloc(0).toString("hex"))
+    expect(dataFrame?.type).toBe(V3FrameType.DATA)
+    expect(dataFrame?.flags).toBe(0)
+    expect(dataFrame?.streamId).toBe(1)
+    expect(dataFrame?.sequence).toBe(3)
+    if (!dataFrame) throw new Error("expected a decoded v3 DATA frame")
+    expect(Buffer.from(dataFrame.payload).toString("hex")).toBe(Buffer.from("abc").toString("hex"))
+  })
 
-test("v3 framing rejects control/data stream confusion and oversized payloads", () => {
-  assert.throws(
-    () => encodeV3Frame({type: V3FrameType.DATA, streamId: 0, sequence: 1}, Buffer.from("x")),
-    /stream ID zero/i
-  )
-  assert.throws(
-    () => encodeV3Frame({type: V3FrameType.AUTH, streamId: 1, sequence: 0}, Buffer.from("x")),
-    /connection control/i
-  )
-  assert.throws(() => encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 0, flags: 1}), /flags/i)
+  it("v3 framing rejects control/data stream confusion and oversized payloads", () => {
+    expect(() => encodeV3Frame({type: V3FrameType.DATA, streamId: 0, sequence: 1}, Buffer.from("x"))).toThrow(/stream ID zero/i)
+    expect(() => encodeV3Frame({type: V3FrameType.AUTH, streamId: 1, sequence: 0}, Buffer.from("x"))).toThrow(/connection control/i)
+    expect(() => encodeV3Frame({type: V3FrameType.PING, streamId: 0, sequence: 0, flags: 1})).toThrow(/flags/i)
 
-  const decoder = new V3FrameDecoder({maxFrameBytes: 2, maxBufferedBytes: 64})
-  assert.throws(
-    () => decoder.push(encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc"))),
-    /payload length/i
-  )
-})
+    const decoder = new V3FrameDecoder({maxFrameBytes: 2, maxBufferedBytes: 64})
+    expect(() => decoder.push(encodeV3Frame({type: V3FrameType.DATA, streamId: 1, sequence: 3}, Buffer.from("abc")))).toThrow(/payload length/i)
+  })
 
-test("v3 control payloads are bounded strict JSON objects", () => {
-  const encoded = encodeV3Control({token: "secret", versions: [3]}, 128)
-  assert.deepEqual(decodeV3Control(encoded, 128), {token: "secret", versions: [3]})
-  assert.throws(() => encodeV3Control(["not-an-object"], 128), /object/i)
-  assert.throws(() => decodeV3Control(Buffer.from("[]"), 128), /object/i)
-  assert.throws(() => encodeV3Control({padding: "x".repeat(129)}, 128), /limit/i)
-})
+  it("v3 control payloads are bounded strict JSON objects", () => {
+    const encoded = encodeV3Control({token: "secret", versions: [3]}, 128)
+    expect(decodeV3Control(encoded, 128)).toEqual({token: "secret", versions: [3]})
+    expect(() => encodeV3Control(["not-an-object"], 128)).toThrow(/object/i)
+    expect(() => decodeV3Control(Buffer.from("[]"), 128)).toThrow(/object/i)
+    expect(() => encodeV3Control({padding: "x".repeat(129)}, 128)).toThrow(/limit/i)
+  })
 
-test("v3 reserves one negotiated compression flag for DATA only", () => {
-  const wire = encodeV3Frame({type: V3FrameType.DATA, streamId: 2, sequence: 10, flags: V3FrameFlag.DATA_COMPRESSED}, Buffer.from("payload"))
-  assert.equal(new V3FrameDecoder().push(wire)[0]?.flags, V3FrameFlag.DATA_COMPRESSED)
-  assert.throws(() => encodeV3Frame({type: V3FrameType.GATEWAY_REGISTER, streamId: 0, sequence: 1, flags: V3FrameFlag.DATA_COMPRESSED}), /flags/i)
+  it("v3 reserves one negotiated compression flag for DATA only", () => {
+    const wire = encodeV3Frame({type: V3FrameType.DATA, streamId: 2, sequence: 10, flags: V3FrameFlag.DATA_COMPRESSED}, Buffer.from("payload"))
+    expect(new V3FrameDecoder().push(wire)[0]?.flags).toBe(V3FrameFlag.DATA_COMPRESSED)
+    expect(() => encodeV3Frame({type: V3FrameType.GATEWAY_REGISTER, streamId: 0, sequence: 1, flags: V3FrameFlag.DATA_COMPRESSED})).toThrow(/flags/i)
+  })
 })

package/test/unit/release-configuration.test.js

@@ -1,21 +1,24 @@
 // @ts-check
 
-import assert from "node:assert/strict"
+import {describe, expect, it} from "@velocious/testing"
 import {readFile} from "node:fs/promises"
 import {fileURLToPath} from "node:url"
-import test from "node:test"
 
 const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url))
 
-test("patch releases use release-patch", async () => {
-  const packageJson = /** @type {{devDependencies: Record<string, string>, private?: boolean, scripts: Record<string, string>}} */ (JSON.parse(await readFile(packageJsonPath, "utf8")))
+describe("release configuration", () => {
+  it("patch releases use release-patch", async () => {
+    const packageJson = /** @type {{devDependencies: Record<string, string>, private?: boolean, scripts: Record<string, string>}} */ (JSON.parse(await readFile(packageJsonPath, "utf8")))
 
-  assert.equal(packageJson.private, undefined)
-  assert.equal(packageJson.devDependencies["release-patch"], "^1.0.8")
-  const check = packageJson.scripts.check
-  const releasePatch = packageJson.scripts["release:patch"]
-  assert.ok(check)
-  assert.ok(releasePatch)
-  assert.deepEqual(check.split(" && "), ["npm run lint", "npm run typecheck", "npm test"])
-  assert.deepEqual(releasePatch.split(" && "), ["npm run check", "release-patch"])
+    expect(packageJson.private).toBe(undefined)
+    expect(packageJson.devDependencies["release-patch"]).toBe("^1.0.8")
+    const check = packageJson.scripts.check
+    const releasePatch = packageJson.scripts["release:patch"]
+    expect(check).toBeTruthy()
+    expect(releasePatch).toBeTruthy()
+    if (check === undefined) throw new Error("Expected a check script")
+    if (releasePatch === undefined) throw new Error("Expected a release:patch script")
+    expect(check.split(" && ")).toEqual(["npm run lint", "npm run typecheck", "npm test"])
+    expect(releasePatch.split(" && ")).toEqual(["npm run check", "release-patch"])
+  })
 })

package/test/unit/reverse/disconnect-attribution.test.js

@@ -1,6 +1,5 @@
-import assert from "node:assert/strict"
+import {describe, expect, it} from "@velocious/testing"
 import {createHmac} from "node:crypto"
-import test from "node:test"
 
 import {
   attachDisconnectAttribution,
@@ -10,73 +9,75 @@ import {
   sanitizePeerControlDetail
 } from "../../../src/reverse/disconnect-attribution.js"
 
-test("disconnect attribution uses one bounded incident and named generations", () => {
-  const attribution = createDisconnectAttribution({
-    disconnectReason: "remote_socket_error",
-    incidentOrigin: "reverse_hub",
-    physicalRole: "gateway",
-    clientConnectionGeneration: 17,
-    gatewayConnectionGeneration: 23,
-    fanOutCount: 5,
-    resumeSuccessCount: 2,
-    terminalStreamCount: 1
-  })
-
-  assert.match(attribution.disconnectIncidentId, /^[A-Za-z0-9_-]{22}$/)
-  assert.deepEqual(parseDisconnectAttribution(attribution), attribution)
-  assert.equal("generation" in attribution, false)
+describe("disconnect attribution", () => {
+  it("disconnect attribution uses one bounded incident and named generations", () => {
+    const attribution = createDisconnectAttribution({
+      disconnectReason: "remote_socket_error",
+      incidentOrigin: "reverse_hub",
+      physicalRole: "gateway",
+      clientConnectionGeneration: 17,
+      gatewayConnectionGeneration: 23,
+      fanOutCount: 5,
+      resumeSuccessCount: 2,
+      terminalStreamCount: 1
+    })
 
-  const error = /** @type {Error & Record<string, unknown>} */ (attachDisconnectAttribution(Object.assign(new Error("classified terminal"), {code: "GATEWAY_DISCONNECTED"}), attribution))
-  assert.equal(error.code, "GATEWAY_DISCONNECTED")
-  assert.equal(error.disconnectReason, "remote_socket_error")
-  assert.equal(error.disconnectIncidentId, attribution.disconnectIncidentId)
-  assert.equal(error.gatewayConnectionGeneration, 23)
-})
+    expect(attribution.disconnectIncidentId).toMatch(/^[A-Za-z0-9_-]{22}$/)
+    expect(parseDisconnectAttribution(attribution)).toEqual(attribution)
+    expect("generation" in attribution).toBe(false)
 
-test("peer control detail cannot assert hub-owned disconnect fields", () => {
-  const result = sanitizePeerControlDetail({
-    code: "TARGET_CLOSED",
-    disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
-    disconnectReason: "hub_shutdown",
-    incidentOrigin: "reverse_hub",
-    physicalRole: "gateway",
-    gatewayConnectionGeneration: 9,
-    fanOutCount: 4,
-    target: "docker.internal:2375",
-    token: "secret"
+    const error = /** @type {Error & Record<string, unknown>} */ (attachDisconnectAttribution(Object.assign(new Error("classified terminal"), {code: "GATEWAY_DISCONNECTED"}), attribution))
+    expect(error.code).toBe("GATEWAY_DISCONNECTED")
+    expect(error.disconnectReason).toBe("remote_socket_error")
+    expect(error.disconnectIncidentId).toBe(attribution.disconnectIncidentId)
+    expect(error.gatewayConnectionGeneration).toBe(23)
   })
 
-  assert.deepEqual(result.detail, {code: "TARGET_CLOSED"})
-  assert.equal(result.reservedFieldsStripped, 6)
-})
+  it("peer control detail cannot assert hub-owned disconnect fields", () => {
+    const result = sanitizePeerControlDetail({
+      code: "TARGET_CLOSED",
+      disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
+      disconnectReason: "hub_shutdown",
+      incidentOrigin: "reverse_hub",
+      physicalRole: "gateway",
+      gatewayConnectionGeneration: 9,
+      fanOutCount: 4,
+      target: "docker.internal:2375",
+      token: "secret"
+    })
 
-test("hub connection fingerprints are keyed, role-separated, and truncated to 128 bits", () => {
-  const key = Buffer.alloc(32, 0x5a)
-  const connectionId = "low_entropy_connection_01"
-  const expected = createHmac("sha256", key)
-    .update("socketduct-connection-id:v1")
-    .update(Buffer.from([0]))
-    .update("gateway")
-    .update(Buffer.from([0]))
-    .update(connectionId)
-    .digest()
-    .subarray(0, 16)
-    .toString("hex")
+    expect(result.detail).toEqual({code: "TARGET_CLOSED"})
+    expect(result.reservedFieldsStripped).toBe(6)
+  })
 
-  const actual = connectionFingerprint(key, "gateway", connectionId)
-  assert.equal(actual, expected)
-  assert.match(actual, /^[a-f0-9]{32}$/)
-  assert.notEqual(actual, connectionId)
-  assert.notEqual(actual, connectionFingerprint(key, "client", connectionId))
-  assert.throws(() => connectionFingerprint(Buffer.alloc(31), "gateway", connectionId), /at least 32 bytes/)
-})
+  it("hub connection fingerprints are keyed, role-separated, and truncated to 128 bits", () => {
+    const key = Buffer.alloc(32, 0x5a)
+    const connectionId = "low_entropy_connection_01"
+    const expected = createHmac("sha256", key)
+      .update("socketduct-connection-id:v1")
+      .update(Buffer.from([0]))
+      .update("gateway")
+      .update(Buffer.from([0]))
+      .update(connectionId)
+      .digest()
+      .subarray(0, 16)
+      .toString("hex")
+
+    const actual = connectionFingerprint(key, "gateway", connectionId)
+    expect(actual).toBe(expected)
+    expect(actual).toMatch(/^[a-f0-9]{32}$/)
+    expect(actual).not.toBe(connectionId)
+    expect(actual).not.toBe(connectionFingerprint(key, "client", connectionId))
+    expect(() => connectionFingerprint(Buffer.alloc(31), "gateway", connectionId)).toThrow(/at least 32 bytes/)
+  })
 
-test("malformed attribution is rejected instead of partially trusted", () => {
-  assert.equal(parseDisconnectAttribution({
-    disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
-    disconnectReason: "not-a-reason",
-    incidentOrigin: "reverse_hub",
-    physicalRole: "gateway",
-    gatewayConnectionGeneration: 1
-  }), undefined)
+  it("malformed attribution is rejected instead of partially trusted", () => {
+    expect(parseDisconnectAttribution({
+      disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
+      disconnectReason: "not-a-reason",
+      incidentOrigin: "reverse_hub",
+      physicalRole: "gateway",
+      gatewayConnectionGeneration: 1
+    })).toBeUndefined()
+  })
 })

package/test/unit/reverse-terminal-outcomes.test.js

@@ -1,54 +1,57 @@
-import assert from "node:assert/strict"
-import test from "node:test"
+import {describe, expect, it} from "@velocious/testing"
 
 import {insertBoundedTerminalOutcome, ownerMayMissTerminalDelivery} from "../../src/reverse/terminal-outcomes.js"
 
-test("a healthy attached physical does not retain a terminal outcome; absent, closing, and pending-resume states do", () => {
-  // Healthy attached: the peer receives the terminal frame and retires the
-  // stream locally, so it never re-presents it. Retaining here is the
-  // unbounded-growth bug: it must be a no-eligibility (no retention).
-  assert.equal(ownerMayMissTerminalDelivery({closing: false, resumeRequired: false}), false)
-  // Detached (no physical): the terminal frame cannot be delivered.
-  assert.equal(ownerMayMissTerminalDelivery(undefined), true)
-  // Closing: the frame may not be flushed.
-  assert.equal(ownerMayMissTerminalDelivery({closing: true, resumeRequired: false}), true)
-  // Paired-resume / pending-manifest state: the frame is answered through the
-  // RESUME manifest instead of a live relay.
-  assert.equal(ownerMayMissTerminalDelivery({closing: false, resumeRequired: true}), true)
-})
-
-test("retention is capped at the owner stream bound, evicting the oldest first in deterministic insertion order", () => {
-  const outcomes = new Map()
-  const limit = 3
-  const outcome = (/** @type {string} */ code) => ({code, attribution: undefined})
-
-  // Within the bound: every outcome is retained, in insertion order.
-  insertBoundedTerminalOutcome(outcomes, "s1\0a", outcome("RESUME_STREAM_OMITTED"), limit)
-  insertBoundedTerminalOutcome(outcomes, "s2\0b", outcome("BUFFER_LIMIT"), limit)
-  assert.equal(outcomes.size, 2)
-  assert.deepEqual([...outcomes.keys()], ["s1\0a", "s2\0b"])
-
-  // Exactly at the bound: no eviction yet.
-  insertBoundedTerminalOutcome(outcomes, "s3\0c", outcome("TARGET_CLOSED"), limit)
-  assert.equal(outcomes.size, 3)
-  assert.equal(outcomes.get("s1\0a")?.code, "RESUME_STREAM_OMITTED")
-
-  // One past the bound: the oldest (s1) is evicted, the newest (s3) is kept.
-  insertBoundedTerminalOutcome(outcomes, "s4\0d", outcome("RESUME_SESSION_LOST"), limit)
-  assert.equal(outcomes.size, 3)
-  assert.equal(outcomes.has("s1\0a"), false, "the oldest outcome must be evicted (fail-closed to RESUME_SESSION_LOST)")
-  assert.deepEqual([...outcomes.keys()], ["s2\0b", "s3\0c", "s4\0d"])
-  assert.equal(outcomes.get("s4\0d")?.code, "RESUME_SESSION_LOST", "the newest causal code must be retained")
-
-  // Further churn keeps the bound and evicts the next-oldest, deterministically.
-  insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("GATEWAY_MAINTENANCE"), limit)
-  assert.equal(outcomes.size, 3)
-  assert.deepEqual([...outcomes.keys()], ["s3\0c", "s4\0d", "s5\0e"])
-  assert.equal(outcomes.has("s2\0b"), false)
-
-  // Re-inserting a retained key updates it in place without disturbing the bound.
-  insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("BUFFER_LIMIT"), limit)
-  assert.equal(outcomes.size, 3)
-  assert.equal(outcomes.get("s5\0e")?.code, "BUFFER_LIMIT")
-  assert.deepEqual([...outcomes.keys()], ["s3\0c", "s4\0d", "s5\0e"])
+describe("reverse terminal outcomes", () => {
+  it("a healthy attached physical does not retain a terminal outcome; absent, closing, and pending-resume states do", () => {
+    // Healthy attached: the peer receives the terminal frame and retires the
+    // stream locally, so it never re-presents it. Retaining here is the
+    // unbounded-growth bug: it must be a no-eligibility (no retention).
+    expect(ownerMayMissTerminalDelivery({closing: false, resumeRequired: false})).toBe(false)
+    // Detached (no physical): the terminal frame cannot be delivered.
+    expect(ownerMayMissTerminalDelivery(undefined)).toBe(true)
+    // Closing: the frame may not be flushed.
+    expect(ownerMayMissTerminalDelivery({closing: true, resumeRequired: false})).toBe(true)
+    // Paired-resume / pending-manifest state: the frame is answered through the
+    // RESUME manifest instead of a live relay.
+    expect(ownerMayMissTerminalDelivery({closing: false, resumeRequired: true})).toBe(true)
+  })
+
+  it("retention is capped at the owner stream bound, evicting the oldest first in deterministic insertion order", () => {
+    const outcomes = new Map()
+    const limit = 3
+    const outcome = (/** @type {string} */ code) => ({code, attribution: undefined})
+
+    // Within the bound: every outcome is retained, in insertion order.
+    insertBoundedTerminalOutcome(outcomes, "s1\0a", outcome("RESUME_STREAM_OMITTED"), limit)
+    insertBoundedTerminalOutcome(outcomes, "s2\0b", outcome("BUFFER_LIMIT"), limit)
+    expect(outcomes.size).toBe(2)
+    expect([...outcomes.keys()]).toEqual(["s1\0a", "s2\0b"])
+
+    // Exactly at the bound: no eviction yet.
+    insertBoundedTerminalOutcome(outcomes, "s3\0c", outcome("TARGET_CLOSED"), limit)
+    expect(outcomes.size).toBe(3)
+    expect(outcomes.get("s1\0a")?.code).toBe("RESUME_STREAM_OMITTED")
+
+    // One past the bound: the oldest (s1) is evicted, the newest (s3) is kept.
+    insertBoundedTerminalOutcome(outcomes, "s4\0d", outcome("RESUME_SESSION_LOST"), limit)
+    expect(outcomes.size).toBe(3)
+    // the oldest outcome must be evicted (fail-closed to RESUME_SESSION_LOST)
+    expect(outcomes.has("s1\0a")).toBe(false)
+    expect([...outcomes.keys()]).toEqual(["s2\0b", "s3\0c", "s4\0d"])
+    // the newest causal code must be retained
+    expect(outcomes.get("s4\0d")?.code).toBe("RESUME_SESSION_LOST")
+
+    // Further churn keeps the bound and evicts the next-oldest, deterministically.
+    insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("GATEWAY_MAINTENANCE"), limit)
+    expect(outcomes.size).toBe(3)
+    expect([...outcomes.keys()]).toEqual(["s3\0c", "s4\0d", "s5\0e"])
+    expect(outcomes.has("s2\0b")).toBe(false)
+
+    // Re-inserting a retained key updates it in place without disturbing the bound.
+    insertBoundedTerminalOutcome(outcomes, "s5\0e", outcome("BUFFER_LIMIT"), limit)
+    expect(outcomes.size).toBe(3)
+    expect(outcomes.get("s5\0e")?.code).toBe("BUFFER_LIMIT")
+    expect([...outcomes.keys()]).toEqual(["s3\0c", "s4\0d", "s5\0e"])
+  })
 })