socketduct 0.1.22 → 0.1.23

package/changelog.d/20260928233813-reverse-retained-terminal-outcomes.md

@@ -0,0 +1,3 @@
+# Preserve terminal outcomes and coordinate paired resume deadlines for retained reverse streams
+
+The reverse hub now retains the exact terminal code and incident attribution for a stream that ends while its peer owner is still resumable, so a reconnecting peer that presents the stream in its resume manifest receives the causal result instead of `RESUME_SESSION_LOST` (genuinely absent state still fails closed with `RESUME_SESSION_LOST`). While a final resume manifest waits on a temporarily detached counterpart, the hub extends the pair's original resume deadline by at most one additional resume window, once per retention episode, so reconnect backoff equal to the window no longer loses resumable streams.

package/changelog.d/20260929023727-reverse-terminal-outcome-bounds.md

@@ -0,0 +1,3 @@
+# Bound retained reverse terminal outcomes and retain them only when delivery may have been missed
+
+The reverse hub now retains a stream's exact terminal outcome only for an owner that may genuinely have missed the terminal delivery (physically absent, closing, or in paired-resume/pending-manifest state) — a healthy attached owner that receives the frame retains nothing — and hard-caps each owner's retained outcomes at the configured per-owner stream bound, evicting the oldest first. This prevents unbounded hub memory growth from authenticated stream churn while evicted streams still fail closed with `RESUME_SESSION_LOST` (never a replay or a target reopen).

package/docs/reverse-gateway.md

@@ -98,7 +98,13 @@ replays only durable chunks above the receiver-confirmed high-water position,
 with its flow-control window reduced by bytes already buffered but not yet
 consumed at the receiver. A registered gateway completing this paired resume is
 not healthy or eligible for a new selection or `OPEN`; retained peers alone may
-attach to submit their resume manifests.
+attach to submit their resume manifests. A stream that terminates while its
+peer owner is still retained keeps its exact terminal code and incident
+attribution, and a reconnecting peer that presents the stream in its resume
+manifest receives that causal result; genuinely absent state still fails closed
+with `RESUME_SESSION_LOST`. While a final resume manifest waits on a
+temporarily detached counterpart, the hub extends the pair's original resume
+deadline by at most one additional resume window, once per retention episode.
 
 The hub owns a separate ordered output queue for every client and gateway
 physical connection. Each queue defaults to a 32 MiB bound and can be set with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socketduct",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Resilient authenticated tunnel/proxy for keeping socket streams alive across flaky links.",
   "type": "module",
   "main": "./src/index.js",

package/src/reverse/hub.js

@@ -32,6 +32,7 @@ import {
   sanitizePeerControlDetail,
   validateFingerprintKeyEpoch
 } from "./disconnect-attribution.js"
+import {insertBoundedTerminalOutcome, ownerMayMissTerminalDelivery} from "./terminal-outcomes.js"
 
 const DEFAULT_OUTPUT_BUFFER_BYTES = 32 * 1024 * 1024
 const DEFAULT_RESUME_MS = 60_000
@@ -84,8 +85,9 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {number} resumeNextPage
  * @property {Array<Record<string, unknown>>} resumeItems
  * @property {boolean} resumeFinal
- * @property {Array<{streamId: number, bridge: Bridge | undefined, code?: string}>} resumeEntries
+ * @property {Array<{streamId: number, bridge: Bridge | undefined, code?: string, attribution?: import('./disconnect-attribution.js').DisconnectAttribution}>} resumeEntries
  * @property {ReturnType<typeof setTimeout> | undefined} resumeTimer
+ * @property {boolean} resumeExtended - Whether this physical already used its one bounded paired-resume extension.
  * @property {(() => void) | undefined} clearHandshake
  * @property {HubOutputItem[]} outputQueue
  * @property {number} outputBytes
@@ -97,6 +99,7 @@ const MANIFEST_PAGE_STREAMS = 64
  * @typedef {object} HubOutputItem
  * @property {Buffer} bytes
  * @property {(delivered: boolean) => void} resolve
+ * @typedef {{code: string, attribution: import('./disconnect-attribution.js').DisconnectAttribution | undefined}} TerminalOutcome
  * @typedef {object} GatewayOwner
  * @property {string} gatewayId
  * @property {string} connectionId
@@ -104,7 +107,10 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {number} generation
  * @property {HubPhysical | undefined} physical
  * @property {Map<number, Bridge>} streams
+ * @property {Map<string, TerminalOutcome>} terminalOutcomes - Exact terminal outcomes for streams this owner may still present.
  * @property {ReturnType<typeof setTimeout> | undefined} expiryTimer
+ * @property {number | undefined} detachedAt - Epoch start of the current retention episode.
+ * @property {boolean} expiryExtended - Whether the current episode already used its one bounded extension.
  * @typedef {object} ClientOwner
  * @property {string} connectionId
  * @property {string} userId
@@ -113,7 +119,10 @@ const MANIFEST_PAGE_STREAMS = 64
  * @property {Map<number, Bridge>} streams
  * @property {string | undefined} gatewayId
  * @property {string | undefined} routeClass
+ * @property {Map<string, TerminalOutcome>} terminalOutcomes - Exact terminal outcomes for streams this owner may still present.
  * @property {ReturnType<typeof setTimeout> | undefined} expiryTimer
+ * @property {number | undefined} detachedAt - Epoch start of the current retention episode.
+ * @property {boolean} expiryExtended - Whether the current episode already used its one bounded extension.
  * @typedef {object} Bridge
  * @property {HubPhysical} client
  * @property {ClientOwner} clientOwner
@@ -225,6 +234,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       resumeFinal: false,
       resumeEntries: [],
       resumeTimer: undefined,
+      resumeExtended: false,
       clearHandshake: undefined,
       outputQueue: [],
       outputBytes: 0,
@@ -362,11 +372,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       streams: new Map(),
       gatewayId: undefined,
       routeClass: undefined,
-      expiryTimer: undefined
+      terminalOutcomes: new Map(),
+      expiryTimer: undefined,
+      detachedAt: undefined,
+      expiryExtended: false
     }
     owner.generation = physical.generation
     owner.physical = physical
     owner.expiryTimer = undefined
+    owner.detachedAt = undefined
+    owner.expiryExtended = false
     physical.streams = owner.streams
     physical.lastClientStreamId = Math.max(0, ...owner.streams.keys())
     physical.resumeRequired = existing !== undefined && owner.streams.size > 0
@@ -415,11 +430,16 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       generation: physical.generation,
       physical: undefined,
       streams: new Map(),
-      expiryTimer: undefined
+      terminalOutcomes: new Map(),
+      expiryTimer: undefined,
+      detachedAt: undefined,
+      expiryExtended: false
     }
     owner.generation = physical.generation
     owner.physical = physical
     owner.expiryTimer = undefined
+    owner.detachedAt = undefined
+    owner.expiryExtended = false
     physical.streams = owner.streams
     physical.nextGatewayStreamId = Math.max(0, ...owner.streams.keys()) + 2
     physical.resumeRequired = existing !== undefined && owner.streams.size > 0
@@ -480,7 +500,15 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       presented.add(item.streamId)
       const bridge = physical.streams.get(item.streamId)
       if (bridge === undefined) {
-        physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: "RESUME_SESSION_LOST"})
+        const owner = physical.role === "client" ? clients.get(/** @type {string} */ (physical.connectionId)) : gateways.get(/** @type {string} */ (physical.gatewayId))
+        const retainedKey = `${item.streamId}\0${item.identifier}`
+        const retained = owner === undefined ? undefined : owner.terminalOutcomes.get(retainedKey)
+        if (owner !== undefined && retained !== undefined) {
+          owner.terminalOutcomes.delete(retainedKey)
+          physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: retained.code, ...(retained.attribution === undefined ? {} : {attribution: retained.attribution})})
+        } else {
+          physical.resumeEntries.push({streamId: item.streamId, bridge: undefined, code: "RESUME_SESSION_LOST"})
+        }
         continue
       }
       if (bridge.identifier !== item.identifier) {
@@ -506,6 +534,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     physical.resumeItems = []
     physical.resumeFinal = true
     await tryCompleteResumes()
+    if (physical.resumeRequired) coordinateResumeDeadlines(physical)
   }
 
   /** Completes physical resume responses only after both logical endpoints have declared durable positions. */
@@ -538,7 +567,19 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
         for (const entry of physical.resumeEntries) {
           const bridge = entry.bridge
           if (bridge === undefined || !bridgeStillOwned(bridge)) {
-            results.push({streamId: entry.streamId, status: "reset", code: entry.code ?? "RESUME_SESSION_LOST"})
+            let code = entry.code ?? "RESUME_SESSION_LOST"
+            let attribution = entry.attribution
+            if (bridge !== undefined) {
+              const owner = physical.role === "client" ? clients.get(/** @type {string} */ (physical.connectionId)) : gateways.get(/** @type {string} */ (physical.gatewayId))
+              const retainedKey = `${entry.streamId}\0${bridge.identifier}`
+              const retained = owner === undefined ? undefined : owner.terminalOutcomes.get(retainedKey)
+              if (owner !== undefined && retained !== undefined) {
+                owner.terminalOutcomes.delete(retainedKey)
+                code = retained.code
+                attribution = retained.attribution
+              }
+            }
+            results.push({streamId: entry.streamId, status: "reset", code, ...(attribution === undefined ? {} : attribution)})
             continue
           }
           try {
@@ -594,6 +635,37 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     physical.resumeTimer = undefined
   }
 
+  /**
+   * Coordinates the paired resume deadlines while a final manifest waits on a
+   * temporarily detached counterpart: one bounded extension of the original
+   * retention deadlines so reconnect backoff equal to the window cannot win.
+   */
+  function coordinateResumeDeadlines(/** @type {HubPhysical} */ physical) {
+    let deadline
+    for (const entry of physical.resumeEntries) {
+      const bridge = entry.bridge
+      if (bridge === undefined || !bridgeStillOwned(bridge)) continue
+      const peerOwner = physical.role === "client" ? bridge.gatewayOwner : bridge.clientOwner
+      if (peerOwner.physical !== undefined || peerOwner.expiryTimer === undefined || peerOwner.detachedAt === undefined) continue
+      if (peerOwner.expiryExtended !== true) {
+        peerOwner.expiryExtended = true
+        const extendedDeadline = peerOwner.detachedAt + 2 * resumeWindowMs
+        clearTimeout(peerOwner.expiryTimer)
+        peerOwner.expiryTimer = setTimeout(() => {
+          void expireOwner(peerOwner, physical.role === "client" ? "gateway" : "client")
+        }, Math.max(0, extendedDeadline - Date.now()))
+        peerOwner.expiryTimer.unref?.()
+      }
+      const peerDeadline = peerOwner.detachedAt + (peerOwner.expiryExtended === true ? 2 : 1) * resumeWindowMs
+      deadline = Math.max(deadline ?? peerDeadline, peerDeadline)
+    }
+    if (deadline === undefined || physical.resumeExtended === true || physical.resumeTimer === undefined || deadline <= Date.now()) return
+    physical.resumeExtended = true
+    clearTimeout(physical.resumeTimer)
+    physical.resumeTimer = setTimeout(() => terminate(physical, "RESUME_WINDOW_EXPIRED"), deadline - Date.now())
+    physical.resumeTimer.unref?.()
+  }
+
   /** Reconciles one bridge to receiver-committed byte positions for a fresh physical generation. */
   function reconcileBridge(/** @type {Bridge} */ bridge) {
     const client = bridge.clientResume
@@ -808,6 +880,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
       forwardControl(destination, frame.type, destinationStreamId, frame.sequence, detail)
       if (frame.type === V3FrameType.RESET || fromClient) {
         removeBridge(bridge)
+        if (typeof detail.code === "string") retainTerminalOutcome(bridge, detail.code, attribution)
         if (attribution !== undefined && bridge.disconnectAttribution !== undefined) {
           logDiagnostic(options.logger, "reverse_hub.streams_reset", {
             ...attribution,
@@ -840,6 +913,33 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     forwardOutput(destination, encodeV3Frame({type, streamId, sequence}, encodeV3Control(value)))
   }
 
+  /**
+   * Retains the exact terminal outcome for each still-registered owner that may
+   * genuinely have missed the terminal delivery, bounded to that owner's stream
+   * limit. A healthy attached owner already received the frame and will not
+   * re-present the stream, so it retains nothing.
+   * @param {Bridge} bridge - Stream.
+   * @param {string} code - Terminal code.
+   * @param {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Incident attribution.
+   */
+  function retainTerminalOutcome(bridge, code, attribution) {
+    retainTerminalOutcomeFor(clients.get(bridge.clientOwner.connectionId), bridge.clientOwner, `${bridge.clientStreamId}\0${bridge.identifier}`, code, attribution)
+    retainTerminalOutcomeFor(gateways.get(bridge.gatewayOwner.gatewayId), bridge.gatewayOwner, `${bridge.gatewayStreamId}\0${bridge.identifier}`, code, attribution)
+  }
+
+  /**
+   * @param {ClientOwner | GatewayOwner | undefined} owner - Current owner record.
+   * @param {ClientOwner | GatewayOwner} bridgeOwner - Owner recorded on the bridge.
+   * @param {string} key - Stream identity key.
+   * @param {string} code - Terminal code.
+   * @param {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Incident attribution.
+   */
+  function retainTerminalOutcomeFor(owner, bridgeOwner, key, code, attribution) {
+    if (owner === undefined || owner !== bridgeOwner) return
+    if (ownerMayMissTerminalDelivery(owner.physical) !== true) return
+    insertBoundedTerminalOutcome(owner.terminalOutcomes, key, {code, attribution}, maxStreams)
+  }
+
   /** @param {Bridge} bridge - Stream. @param {string} code - Reset code. @param {HubPhysical} [excluded] - Already-dead peer. @returns {Promise<void>} Terminal control delivery. */
   function closeBridge(bridge, code, excluded) {
     const owned = bridgeStillOwned(bridge)
@@ -854,6 +954,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     if (bridge.client !== excluded && !bridge.client.socket.destroyed) deliveries.push(sendControl(bridge.client, V3FrameType.RESET, bridge.clientStreamId, 0, detail))
     if (bridge.gateway !== excluded && !bridge.gateway.socket.destroyed) deliveries.push(sendControl(bridge.gateway, V3FrameType.RESET, bridge.gatewayStreamId, 0, detail))
     removeBridge(bridge)
+    retainTerminalOutcome(bridge, code, attribution)
     if (attribution !== undefined) logDiagnostic(options.logger, "reverse_hub.streams_reset", {
       ...attribution,
       gatewayId: bridge.gatewayOwner.gatewayId,
@@ -999,6 +1100,10 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
   /** @param {GatewayOwner | ClientOwner} owner - Detached identity. @param {'gateway' | 'client'} role - Owner role. */
   function scheduleOwnerExpiry(owner, role) {
     if (owner.expiryTimer !== undefined) clearTimeout(owner.expiryTimer)
+    if (owner.detachedAt === undefined) {
+      owner.detachedAt = Date.now()
+      owner.expiryExtended = false
+    }
     owner.expiryTimer = setTimeout(() => {
       void expireOwner(owner, role)
     }, resumeWindowMs)
@@ -1010,6 +1115,7 @@ export async function startReverseGatewayHub(/** @type {ReverseGatewayHubOptions
     owner.expiryTimer = undefined
     if (owner.physical !== undefined) return
     for (const bridge of [...owner.streams.values()]) await closeBridge(bridge, "RESUME_WINDOW_EXPIRED")
+    owner.terminalOutcomes.clear()
     if (role === "gateway") {
       const gatewayOwner = /** @type {GatewayOwner} */ (owner)
       if (gateways.get(gatewayOwner.gatewayId) === gatewayOwner) gateways.delete(gatewayOwner.gatewayId)

package/src/reverse/terminal-outcomes.js

@@ -0,0 +1,55 @@
+/**
+ * Bounded, eligibility-gated retention of exact terminal outcomes for reverse
+ * stream owners.
+ *
+ * A retained terminal outcome only matters to an owner that may genuinely have
+ * missed the terminal frame. A healthy attached physical receives the frame and
+ * retires the stream locally, so it never re-presents the stream and must not
+ * accumulate retained outcomes — unbounded growth under authenticated stream
+ * churn would otherwise exhaust hub memory. Retention is additionally hard-capped
+ * to the owner's configured stream bound so that even a detached/resuming owner
+ * cannot retain more outcomes than it could ever present; eviction is fail-closed
+ * (the evicted stream later resolves as RESUME_SESSION_LOST, never a replay or a
+ * target reopen).
+ */
+
+/**
+ * @typedef {object} TerminalOutcome
+ * @property {string} code - Exact terminal classification.
+ * @property {import('./disconnect-attribution.js').DisconnectAttribution | undefined} attribution - Validated incident, when one was in flight.
+ */
+
+/**
+ * @typedef {object} OwnerPhysicalState
+ * @property {boolean} closing - Whether the physical close has begun.
+ * @property {boolean} resumeRequired - Whether the physical is still in its paired-resume / pending-manifest state.
+ */
+
+/**
+ * Decides whether an owner may have missed a terminal delivery and therefore
+ * needs the exact outcome retained for a later resume manifest.
+ * @param {OwnerPhysicalState | undefined} physical - The owner's current physical state.
+ * @returns {boolean} Whether the terminal outcome should be retained for the owner.
+ */
+export function ownerMayMissTerminalDelivery(/** @type {OwnerPhysicalState | undefined} */ physical) {
+  if (physical === undefined) return true
+  return physical.closing || physical.resumeRequired
+}
+
+/**
+ * Inserts one terminal outcome into an owner's bounded retention map, evicting
+ * the oldest entry (deterministic Map insertion order) whenever the insertion
+ * would exceed the bound. Re-inserting a retained key updates it in place.
+ * @param {Map<string, TerminalOutcome>} outcomes - The owner's retained outcomes.
+ * @param {string} key - The stream identity key.
+ * @param {TerminalOutcome} outcome - The terminal outcome to retain.
+ * @param {number} limit - The maximum number of retained outcomes.
+ */
+export function insertBoundedTerminalOutcome(/** @type {Map<string, TerminalOutcome>} */ outcomes, /** @type {string} */ key, /** @type {TerminalOutcome} */ outcome, /** @type {number} */ limit) {
+  outcomes.set(key, outcome)
+  while (outcomes.size > limit) {
+    const oldest = outcomes.keys().next()
+    if (oldest.done === true) break
+    outcomes.delete(/** @type {string} */ (oldest.value))
+  }
+}

package/test/integration/reverse-resume-continuity.test.js

@@ -0,0 +1,333 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {mkdtemp, rm} from "node:fs/promises"
+import {connect as connectTcp, createServer} from "node:net"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import {Duplex} from "node:stream"
+import test from "node:test"
+
+import {StaticTokenStore} from "../../src/auth/static-token-store.js"
+import {OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "../../src/reverse/index.js"
+import {generateTestCertificates} from "../helpers/tls-certificates.js"
+
+/** @param {import('node:net').Server} server - Server. */
+async function listen(server) {
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(undefined) })
+  })
+  const address = server.address()
+  assert(address !== null && typeof address !== "string")
+  return address.port
+}
+
+/** @param {import('node:events').EventEmitter} emitter - Emitter. @param {string} event - Event. */
+async function onceEvent(emitter, event) {
+  await new Promise((resolve, reject) => {
+    emitter.once("error", reject)
+    emitter.once(event, () => { emitter.off("error", reject); resolve(undefined) })
+  })
+}
+
+/** @param {import('node:stream').Duplex} socket - Socket. @param {number} bytes - Expected bytes. */
+async function readBytes(socket, bytes) {
+  return await new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
+    const chunks = []
+    let length = 0
+    const cleanup = () => { socket.off("data", onData); socket.off("error", onError) }
+    /** @param {Error} error - Stream failure. */
+    const onError = (error) => { cleanup(); reject(error) }
+    /** @param {Buffer} chunk - Stream bytes. */
+    const onData = (chunk) => {
+      chunks.push(chunk)
+      length += chunk.length
+      if (length < bytes) return
+      cleanup()
+      resolve(Buffer.concat(chunks))
+    }
+    socket.on("data", onData)
+    socket.on("error", onError)
+  })
+}
+
+/** @param {Promise<unknown>} promise - Work. @param {string} label - Timeout label. */
+async function withTimeout(promise, label) {
+  let timer
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), 2_000) })
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** @param {() => boolean} predicate - Completion predicate. @param {string} label - Failure label. */
+async function waitUntil(predicate, label) {
+  const deadline = Date.now() + 4_000
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error(`Timed out: ${label}`)
+    await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+}
+
+/** @param {import('node:stream').Duplex} socket - Stream. @returns {Promise<Error & {code?: string}>} Next stream error. */
+async function nextError(socket) {
+  return await new Promise((resolve) => socket.once("error", (error) => resolve(/** @type {Error & {code?: string}} */ (error))))
+}
+
+/** Target that records received bytes and can flood the gateway buffer on demand while the peer physical is down. */
+class RecordingInterruptibleTarget extends Duplex {
+  /** @type {Buffer[]} */
+  chunks = []
+
+  constructor() {
+    super()
+    setImmediate(() => this.emit("connect"))
+  }
+
+  /** @override */
+  _read() {}
+
+  /** @param {Buffer} chunk - Received bytes. @param {BufferEncoding} _encoding - Ignored encoding. @param {(error?: Error | null) => void} callback - Completion. @override */
+  _write(chunk, _encoding, callback) {
+    this.chunks.push(Buffer.from(chunk))
+    callback()
+  }
+
+  /** @param {Buffer} payload - Target-originated bytes delivered to the gateway. */
+  flood(payload) { this.emit("data", payload) }
+}
+
+test("a paired resume completes when the first counterpart return lands just past the original resume window", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-resume-extension-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("target:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 250})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "extension_gateway_01", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 350, maxReconnectDelayMs: 350})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "extension_client_01", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({identifier: "extension_stream_01", sessionName: "extension-stream", host: "127.0.0.1", port: targetPort})
+  await onceEvent(socket, "connect")
+  socket.write("before|")
+  const preResponse = readBytes(socket, 14)
+  assert.equal((await withTimeout(preResponse, "pre-resume target echo")).toString(), "target:before|")
+
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  socket.write("after|")
+  const postResponse = readBytes(socket, 13)
+  // The gateway's first return (~350ms) lands after the original 250ms window;
+  // the bounded paired-resume extension must keep both deadlines open for it.
+  await waitUntil(() => gateway.status().physicalConnects >= 2 && gateway.status().physicalState === "ready", "gateway return just past the original window")
+  assert.equal((await withTimeout(postResponse, "post-resume target echo")).toString(), "target:after|")
+  assert.equal(targetAccepts, 1, "resume must keep the original logical target socket")
+  assert.equal(hub.status().virtualStreams, 1)
+
+  const closed = onceEvent(socket, "close")
+  socket.end()
+  await withTimeout(closed, "post-resume cleanup close")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "post-resume ownership cleanup")
+})
+
+test("a retained terminal outcome answers a reconnecting peer with the causal code instead of RESUME_SESSION_LOST", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-retained-outcome-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let acceptsA = 0
+  const targetSocketsA = new Set()
+  const targetA = createServer((socket) => {
+    acceptsA += 1
+    targetSocketsA.add(socket)
+    socket.once("close", () => targetSocketsA.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("a:"), chunk])))
+  })
+  const portA = await listen(targetA)
+  t.after(() => { for (const socket of targetSocketsA) socket.destroy(); return new Promise((resolve) => targetA.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 2_000})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  /** @type {RecordingInterruptibleTarget | undefined} */
+  let targetB
+  let targetBCreates = 0
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "outcome_gateway_01",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"},
+    tls,
+    spoolDirectory: join(root, "gateway-spool"),
+    authorizeTarget: () => true,
+    reconnectDelayMs: 300,
+    maxReconnectDelayMs: 300,
+    maxStreamBufferBytes: 32,
+    createTargetConnection: (target) => {
+      if (target.port === 2376) {
+        targetBCreates += 1
+        targetB = new RecordingInterruptibleTarget()
+        return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (targetB))
+      }
+      return connectTcp(target)
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "outcome_client_01", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 500, maxReconnectDelayMs: 500})
+  t.after(() => client.close())
+  await client.connect()
+  const socketA = client.createConnection({identifier: "outcome_stream_a", sessionName: "outcome-a", host: "127.0.0.1", port: portA})
+  const socketB = client.createConnection({identifier: "outcome_stream_b", sessionName: "outcome-b", host: "target-b", port: 2376})
+  await Promise.all([onceEvent(socketA, "connect"), onceEvent(socketB, "connect")])
+  socketA.write("one|")
+  const preA = readBytes(socketA, 6)
+  assert.equal((await withTimeout(preA, "stream A pre-interruption echo")).toString(), "a:one|")
+  socketB.write("two|")
+  await waitUntil(() => targetB !== undefined && Buffer.concat(targetB.chunks).toString() === "two|", "stream B bytes reached its target")
+  const terminalB = nextError(socketB)
+
+  // The gateway physical dies and the client peer is kicked into a slow (500ms)
+  // reconnect. While both are apart, target B overflows the gateway stream
+  // buffer: the gateway resets and destroys B in memory, but its RESET cannot
+  // reach the hub, so the hub still owns B when the gateway re-registers.
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  await new Promise((resolve) => setTimeout(resolve, 100))
+  assert.equal(client.status().physicalState, "reconnecting", "the client peer must still be mid-reconnect when target B overflows")
+  targetB?.flood(Buffer.alloc(64, 0x42))
+  await waitUntil(() => hub.status().gatewayPhysicalConnections >= 1, "gateway re-registration before the peer returns")
+  assert.equal(targetB?.destroyed, true, "the overflowed stream target must be released in memory")
+
+  const error = /** @type {Error & Record<string, unknown>} */ (await withTimeout(terminalB, "stream B terminal outcome after peer return"))
+  assert.equal(error.code, "RESUME_STREAM_OMITTED", "the reconnecting peer must receive the retained causal code")
+  assert.match(String(error.disconnectIncidentId ?? ""), /^[A-Za-z0-9_-]{22}$/, "the retained outcome must carry the incident attribution")
+
+  const postA = readBytes(socketA, 12)
+  socketA.write("one-after|")
+  assert.equal((await withTimeout(postA, "stream A post-resume echo")).toString(), "a:one-after|")
+  assert.equal(acceptsA, 1, "the surviving stream must resume on its original target")
+  assert.equal(targetBCreates, 1, "the terminal stream must never reopen its target")
+  assert.equal(targetB?.destroyed, true, "the terminal stream target must be released exactly once")
+
+  const closedA = onceEvent(socketA, "close")
+  socketA.end()
+  await withTimeout(closedA, "stream A cleanup close")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSocketsA.size === 0, "retained-outcome ownership cleanup")
+})
+
+test("a paired resume extension is bounded by one window and genuine expiry still releases state", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-resume-bounded-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 250})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "bounded_expiry_gateway", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 1_000, maxReconnectDelayMs: 1_000})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "bounded_expiry_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({identifier: "bounded_stream_01", sessionName: "bounded-stream", host: "127.0.0.1", port: targetPort})
+  const terminal = nextError(socket)
+  await onceEvent(socket, "connect")
+
+  await hub.closeActiveGateway("o2")
+  await waitUntil(() => gateway.status().physicalState === "reconnecting", "gateway interruption")
+  // The gateway returns at ~1000ms, far beyond the one bounded extension
+  // (original 250ms window extended once to 500ms), so the pair must expire.
+  const error = /** @type {Error & {code?: string}} */ (await withTimeout(terminal, "bounded expired resume"))
+  assert.equal(error.code, "RESUME_WINDOW_EXPIRED")
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "bounded expiry releases all retained state")
+  assert.equal(targetAccepts, 1, "the expired stream must not reopen its target")
+})
+
+test("multiple concurrent streams share one physical interruption and resume together on their original targets", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-multi-stream-resume-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  let targetAccepts = 0
+  const targetSockets = new Set()
+  const target = createServer((socket) => {
+    targetAccepts += 1
+    targetSockets.add(socket)
+    socket.once("close", () => targetSockets.delete(socket))
+    socket.on("data", (chunk) => socket.write(Buffer.concat([Buffer.from("t:"), chunk])))
+  })
+  const targetPort = await listen(target)
+  t.after(() => { for (const socket of targetSockets) socket.destroy(); return new Promise((resolve) => target.close(() => resolve(undefined))) })
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  const hub = await startReverseGatewayHub({tokens, tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile}, authorizeGateway: () => true, authorizeClientGateway: () => true, authorizeOpen: () => true, resumeWindowMs: 2_000})
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({gatewayId: "o2", connectionId: "multi_resume_gateway", hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"}, tls, spoolDirectory: join(root, "gateway-spool"), authorizeTarget: () => true, reconnectDelayMs: 30, maxReconnectDelayMs: 30})
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "multi_resume_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, spoolDirectory: join(root, "client-spool"), reconnectDelayMs: 10, maxReconnectDelayMs: 20})
+  t.after(() => client.close())
+  await client.connect()
+  /** @type {import('node:stream').Duplex[]} */
+  const sockets = []
+  /** @type {Promise<string>[]} */
+  const echoes = []
+  for (let index = 1; index <= 3; index += 1) {
+    const socket = client.createConnection({identifier: `multi_stream_${index}`, sessionName: `multi-stream-${index}`, host: "127.0.0.1", port: targetPort})
+    sockets.push(socket)
+    await onceEvent(socket, "connect")
+  }
+  let echoIndex = 1
+  for (const socket of sockets) {
+    socket.write(`pre${echoIndex}|`)
+    echoes.push(readBytes(socket, 2 + 3 + String(echoIndex).length + 1).then((bytes) => bytes.toString()))
+    echoIndex += 1
+  }
+  const preEchoes = await Promise.all(echoes.map((promise) => withTimeout(promise, "pre-resume echo")))
+  assert.deepEqual(preEchoes, ["t:pre1|", "t:pre2|", "t:pre3|"])
+  assert.equal(targetAccepts, 3)
+
+  await hub.closeActiveGateway("o2")
+  let postIndex = 1
+  for (const socket of sockets) {
+    socket.write(`post${postIndex}|`)
+    postIndex += 1
+  }
+  /** @type {Promise<string>[]} */
+  const postEchoes = sockets.map((socket, index) => readBytes(socket, 2 + 4 + String(index + 1).length + 1).then((bytes) => bytes.toString()))
+  await waitUntil(() => gateway.status().physicalConnects >= 2 && gateway.status().physicalState === "ready", "shared gateway re-registration")
+  const postEchoesReceived = await Promise.all(postEchoes.map((promise) => withTimeout(promise, "post-resume echo")))
+  assert.deepEqual(postEchoesReceived, ["t:post1|", "t:post2|", "t:post3|"], "every stream must resume on its original target without cross-stream loss")
+  assert.equal(targetAccepts, 3, "the shared interruption must not create replacement targets")
+  assert.equal(hub.status().virtualStreams, 3)
+
+  const closes = sockets.map((socket) => { socket.end(); return onceEvent(socket, "close") })
+  await Promise.all(closes.map((promise) => withTimeout(promise, "multi-stream cleanup close")))
+  await waitUntil(() => hub.status().virtualStreams === 0 && client.status().virtualStreams === 0 && gateway.status().virtualStreams === 0 && targetSockets.size === 0, "multi-stream ownership cleanup")
+})

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

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+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"])
+})