socketduct 0.1.17 → 0.1.19

package/src/reverse/client.js

@@ -1,11 +1,14 @@
 /* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-jsdoc, jsdoc/require-param, jsdoc/require-property-description, jsdoc/require-returns */
 import {randomBytes} from "node:crypto"
 import {EventEmitter} from "node:events"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
 
 import {availableCodecs, getMaxDecompressedBytes, ZSTD_CODEC, zstdAvailable} from "../protocol/compression.js"
 import {errorDiagnostics, logDiagnostic} from "../logging/structured-logger.js"
 import {decodeV3Data, encodeV3Data, AdaptiveCompressor} from "../protocol/v3-compression.js"
 import {decodeV3Control, encodeV3Control, encodeV3Frame, V3FrameDecoder, V3FrameType} from "../protocol/v3-frame.js"
+import {SessionSpool} from "../spool/spool-file.js"
 import {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "../client/virtual-socket.js"
 import {
   asError,
@@ -27,6 +30,7 @@ import {
 
 const DEFAULT_STREAM_BUFFER_BYTES = 4 * 1024 * 1024
 const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
+const MANIFEST_PAGE_STREAMS = 64
 
 /**
  * @typedef {object} ReverseGatewayConnectionOptions
@@ -40,6 +44,8 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
  * @property {number} [maxStreams] - Concurrent stream limit.
  * @property {number} [maxStreamBufferBytes] - Per-stream client output bound.
  * @property {number} [maxConnectionBufferBytes] - Aggregate client output bound.
+ * @property {string} [spoolDirectory] - Durable replay spool root.
+ * @property {number} [maxAgeMs] - Maximum reverse-stream spool age.
  * @property {number} [connectTimeoutMs] - TLS/auth deadline.
  * @property {number} [reconnectDelayMs] - Initial reconnect delay.
  * @property {number} [maxReconnectDelayMs] - Maximum reconnect delay.
@@ -64,6 +70,8 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
  * @property {{host: string, port: number}} target
  * @property {VirtualSocket} socket
  * @property {'opening' | 'open' | 'half-closed' | 'closed' | 'reset'} state
+ * @property {boolean} opened
+ * @property {boolean} openingSent
  * @property {number} sendSequence
  * @property {number} transmittedSequence
  * @property {number} sendAck
@@ -71,8 +79,9 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
  * @property {number} sendWindowLimit
  * @property {number} receiveSequence
  * @property {number} receiveAck
- * @property {number | undefined} pendingReceiveAck
+ * @property {Array<{sequence: number, remaining: number}>} receiveFrames
  * @property {boolean} remoteEnded
+ * @property {boolean} remoteEndPending
  * @property {number} bufferedBytes
  * @property {ClientChunk[]} replay
  * @property {AdaptiveCompressor} compressor
@@ -82,6 +91,34 @@ const DEFAULT_CONNECTION_BUFFER_BYTES = 32 * 1024 * 1024
  * @property {boolean} localEnded
  * @property {boolean} endSent
  * @property {((error?: Error | null) => void) | undefined} endCallback
+ * @property {Promise<void>} spoolReady
+ * @property {Promise<void>} spoolQueue
+ * @property {number} spoolReservedBytes
+ * @property {Promise<void> | undefined} spoolRemovalPromise
+ * @property {boolean} spoolCleanupFailureRecorded
+ * @property {boolean} ownsSpool
+ * @property {boolean} recoveredObject
+ * @typedef {object} ReverseClientRecoveryState
+ * @property {number} version
+ * @property {'reverse-client'} role
+ * @property {string} connectionId
+ * @property {number} generation
+ * @property {string} [gatewayId]
+ * @property {string} [routeClass]
+ * @property {number} streamId
+ * @property {string} identifier
+ * @property {string} name
+ * @property {{host: string, port: number}} target
+ * @property {'opening' | 'open' | 'half-closed'} state
+ * @property {boolean} opened
+ * @property {true} openingSent
+ * @property {number} sendSequence
+ * @property {number} sendAck
+ * @property {number} receiveSequence
+ * @property {number} receiveAck
+ * @property {boolean} localEnded
+ * @property {boolean} remoteEnded
+ * @property {boolean} endSent
  */
 
 /** Server3/TensorBuzz-facing virtual socket connection to an exact gateway or server-resolved route class. */
@@ -95,10 +132,14 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #generation
   /** @type {string | undefined} */ #codec
   /** @type {boolean} */ #closing = false
+  /** @type {boolean} */ #preserveSpools = false
   /** @type {boolean} */ #fatal = false
   /** @type {Error | undefined} */ #fatalError
   /** @type {boolean} */ #referenced = true
   /** @type {boolean} */ #warm = false
+  /** @type {boolean} */ #resuming = false
+  /** @type {Array<Record<string, unknown>>} */ #resumeResults = []
+  /** @type {number} */ #resumeNextPage = 0
   /** @type {ReturnType<typeof setTimeout> | undefined} */ #reconnectTimer
   /** @type {Promise<void> | undefined} */ #connectPromise
   /** @type {(() => void) | undefined} */ #resolveConnect
@@ -112,6 +153,12 @@ export class ReverseGatewayConnection extends EventEmitter {
   /** @type {number} */ #rawDataBytes = 0
   /** @type {number} */ #wireDataBytes = 0
   /** @type {number} */ #lastProgressedStreamId = 0
+  /** @type {Promise<void>} */ #openQueue = Promise.resolve()
+  /** @type {Promise<void>} */ #physicalFrameQueue = Promise.resolve()
+  /** @type {SessionSpool} */ #spool
+  /** @type {number} */ #spoolBytes = 0
+  /** @type {number} */ #spoolCleanupFailures = 0
+  /** @type {Set<Promise<void>>} */ #spoolCleanupTasks = new Set()
 
   /** @param {ReverseGatewayConnectionOptions} options - Hub route and safety policy. */
   constructor(options) {
@@ -119,6 +166,11 @@ export class ReverseGatewayConnection extends EventEmitter {
     validateOptions(options)
     this.#options = options
     this.#connectionId = options.connectionId ?? randomBytes(24).toString("base64url")
+    this.#spool = new SessionSpool({
+      rootDir: options.spoolDirectory ?? join(tmpdir(), `socketduct-${typeof process.getuid === "function" ? process.getuid() : "user"}`, "reverse-client", this.#connectionId),
+      maxBytes: options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES,
+      maxAgeMs: options.maxAgeMs ?? 24 * 60 * 60 * 1000
+    })
     this.#generation = options.initialGeneration ?? Date.now() * 1000
     this.#reconnectDelay = options.reconnectDelayMs ?? 250
     this.#sendWindowLimit = this.#initialWindow()
@@ -139,15 +191,45 @@ export class ReverseGatewayConnection extends EventEmitter {
 
   /** Allocates one stream on the already-warm gateway transport. */
   createConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback = undefined) {
+    if (options?.recover === true) throw new TypeError("Durable recovery must use registerRecoveredConnection()")
+    return this.#createConnection(options, callback, false)
+  }
+
+  /** Registers one durable stream without starting a physical connection. */
+  registerRecoveredConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback = undefined) {
+    if (options?.recover !== true) throw new TypeError("registerRecoveredConnection requires recover: true")
+    if (this.#options.connectionId === undefined) throw new TypeError("registerRecoveredConnection requires an explicit stable connectionId")
+    if (this.#options.spoolDirectory === undefined) throw new TypeError("registerRecoveredConnection requires an explicit persistent spoolDirectory")
+    if (this.#physicalAttempts > 0) throw new Error("Recovered streams must be registered before any physical connection attempt")
+    return this.#createConnection(options, callback, true)
+  }
+
+  /** Creates a fresh or synchronously recovered reverse stream. */
+  #createConnection(/** @type {import('../client/multiplexed-connection.js').VirtualConnectionOptions} */ options, /** @type {((error: Error | null, socket: VirtualSocket) => void) | undefined} */ callback, /** @type {boolean} */ recovering) {
     if (this.#closing) throw closedError()
-    if (this.#state !== "ready") throw Object.assign(new Error("Reverse gateway member is not ready"), {code: "SOCKETDUCT_TRANSPORT_SET_NOT_READY"})
+    if (!recovering && this.#state !== "ready") throw Object.assign(new Error("Reverse gateway member is not ready"), {code: "SOCKETDUCT_TRANSPORT_SET_NOT_READY"})
     if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum reverse virtual stream count exceeded")
     const target = parseTarget(options?.target ?? {host: options?.host, port: options?.port})
     if (target === undefined) throw new TypeError("Reverse virtual connection target host and port are required")
-    const identifier = options.identifier ?? randomBytes(24).toString("base64url")
+    const identifier = recovering ? options.identifier : (options.identifier ?? randomBytes(24).toString("base64url"))
     if (typeof identifier !== "string" || !STABLE_IDENTIFIER.test(identifier)) throw new TypeError("Reverse virtual stream identifier must be 8-128 URL-safe characters")
-    const id = this.#allocateStreamId()
-    const name = options.sessionName ?? `socketduct-reverse-${id}`
+    const recovery = recovering
+      ? validateRecoveryState(this.#spool.readRecoveryStateSync(identifier, "reverse-client-v3"), {
+        connectionId: this.#connectionId,
+        identifier,
+        target,
+        selection: this.#routeIdentityFields(),
+        initialWindow: this.#initialWindow(),
+        ...(options.sessionName === undefined ? {} : {sessionName: options.sessionName})
+      })
+      : undefined
+    const chunks = recovery === undefined ? [] : this.#spool.loadChunksSync(identifier, "reverse-client-v3", recovery.sendAck, recovery.sendSequence)
+    if (recovery !== undefined) validateRecoveredChunks(recovery, chunks, this.#options.maxStreamBufferBytes ?? DEFAULT_STREAM_BUFFER_BYTES, this.#maxFrameBytes())
+    const bufferedBytes = chunks.reduce((sum, chunk) => sum + chunk.data.length, 0)
+    if (this.#bufferedBytes + bufferedBytes > (this.#options.maxConnectionBufferBytes ?? DEFAULT_CONNECTION_BUFFER_BYTES)) throw new Error("Recovered reverse data exceeds the connection buffer limit")
+    const id = recovery?.streamId ?? this.#allocateStreamId()
+    if (this.#streams.has(id)) throw new Error(`Reverse v3 stream ID ${id} is already active`)
+    const name = options.sessionName ?? recovery?.name ?? `socketduct-reverse-${id}`
     if (typeof name !== "string" || name.length === 0 || name.length > 256) throw new TypeError("Reverse virtual stream name must be 1-256 characters")
     const socket = new VirtualSocket(/** @type {import('../client/multiplexed-connection.js').MultiplexedSocketductConnection} */ (/** @type {unknown} */ (this)), id, {
       ...target,
@@ -158,43 +240,78 @@ export class ReverseGatewayConnection extends EventEmitter {
     /** @type {ReverseClientStream} */
     const stream = {
       id, identifier, name, target, socket,
-      state: "opening",
-      sendSequence: 0,
-      transmittedSequence: 0,
-      sendAck: 0,
+      state: recovery?.state ?? "opening",
+      opened: recovery?.opened ?? false,
+      openingSent: recovery?.openingSent ?? false,
+      sendSequence: recovery?.sendSequence ?? 0,
+      transmittedSequence: recovery?.sendAck ?? 0,
+      sendAck: recovery?.sendAck ?? 0,
       sendWindow: this.#sendWindowLimit,
       sendWindowLimit: this.#sendWindowLimit,
-      receiveSequence: 0,
-      receiveAck: 0,
-      pendingReceiveAck: undefined,
-      remoteEnded: false,
-      bufferedBytes: 0,
-      replay: [],
+      // Bytes buffered only in the dead VirtualSocket were not durably
+      // delivered. Resume inbound delivery from the persisted ACK boundary.
+      receiveSequence: recovery?.receiveAck ?? 0,
+      receiveAck: recovery?.receiveAck ?? 0,
+      receiveFrames: [],
+      remoteEnded: recovery?.remoteEnded ?? false,
+      remoteEndPending: recovery?.remoteEnded ?? false,
+      bufferedBytes,
+      replay: chunks.map((chunk) => ({...chunk, sent: false})),
       compressor: new AdaptiveCompressor(),
       pumping: false,
       pendingWrite: undefined,
       progressingWrite: false,
-      localEnded: false,
-      endSent: false,
-      endCallback: undefined
+      localEnded: recovery?.localEnded ?? false,
+      endSent: recovery?.endSent ?? false,
+      endCallback: undefined,
+      spoolReady: Promise.resolve(),
+      spoolQueue: Promise.resolve(),
+      spoolReservedBytes: bufferedBytes,
+      spoolRemovalPromise: undefined,
+      spoolCleanupFailureRecorded: false,
+      ownsSpool: recovery !== undefined,
+      recoveredObject: recovery !== undefined
+    }
+    if (recovery !== undefined) {
+      this.#options.aggregateBudget?.reserveData(bufferedBytes)
+      this.#bufferedBytes += bufferedBytes
+      this.#spoolBytes += bufferedBytes
+      this.#nextStreamId = Math.max(this.#nextStreamId, id + 2)
+      this.#generation = Math.max(this.#generation, recovery.generation)
     }
     this.#streams.set(id, stream)
+    stream.spoolReady = recovery === undefined
+      ? this.#spool.createNew({sessionId: identifier, ownerId: "reverse-client-v3"})
+        .then(() => {
+          stream.ownsSpool = true
+          return this.#spool.writeRecoveryState(identifier, this.#recoveryState(stream))
+        })
+      : this.#spool.truncateAcked(identifier, recovery.sendAck)
+    stream.spoolQueue = stream.spoolReady.catch(() => {})
     logDiagnostic(this.#options.logger, "virtual_stream.opening", {
       streamId: id,
       generation: this.#generation,
       ...this.#routeIdentityFields(),
-      recovered: false
+      recovered: recovery !== undefined
     })
     if (callback !== undefined) installCallback(socket, callback)
-    void this.#sendControl(V3FrameType.OPEN, id, 0, {...this.#routeIdentityFields(), identifier, name, target, initialWindow: this.#initialWindow()}).catch((error) => socket._receiveError(asError(error)))
+    if (recovery === undefined) {
+      const opening = this.#openQueue
+        .then(() => stream.spoolReady)
+        .then(async () => {
+          if (this.#streams.get(id) !== stream) return
+          stream.openingSent = true
+          await this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(identifier, this.#recoveryState(stream)))
+          if (this.#streams.get(id) === stream) await this.#sendControl(V3FrameType.OPEN, id, 0, {...this.#routeIdentityFields(), identifier, name, target, initialWindow: this.#initialWindow()})
+        })
+      this.#openQueue = opening.then(() => undefined, () => undefined)
+      void opening.catch((error) => socket._receiveError(asError(error)))
+    } else {
+      void stream.spoolReady.catch((error) => socket._receiveError(asError(error)))
+    }
     return socket
   }
 
-  /** Reverse established operations are intentionally not recoverable across process/transport loss. */
-  registerRecoveredConnection() {
-    throw Object.assign(new Error("Reverse gateway streams cannot be recovered; reconcile the Docker operation before retrying"), {code: "REVERSE_STREAM_RECOVERY_UNSUPPORTED"})
-  }
-
   status() {
     /** @type {Record<string, number>} */
     const streamStates = {}
@@ -207,8 +324,8 @@ export class ReverseGatewayConnection extends EventEmitter {
       queuedBytes: this.#bufferedBytes,
       dataQueuedBytes: this.#bufferedBytes,
       controlQueuedBytes: 0,
-      spoolBytes: 0,
-      spoolCleanupFailures: 0,
+      spoolBytes: this.#spoolBytes,
+      spoolCleanupFailures: this.#spoolCleanupFailures,
       physicalConnects: this.#physicalConnects,
       reconnectAttempts: this.#reconnectAttempts,
       reconnectSuccesses: Math.max(0, this.#physicalConnects - 1),
@@ -239,25 +356,51 @@ export class ReverseGatewayConnection extends EventEmitter {
     }
     this.#rejectConnect?.(closedError())
     this.#settleConnect()
+    const cleanup = await Promise.allSettled([...this.#spoolCleanupTasks])
+    const failures = cleanup.filter((result) => result.status === "rejected").map((result) => asError(result.reason))
+    if (failures.length > 0) throw new AggregateError(failures, "Reverse client spool cleanup failed")
   }
 
-  /** Detach is terminal because ambiguous reverse streams are never durably replayed. */
-  detach() { return this.close() }
+  /** Preserves durable streams while retiring this object for replacement. */
+  async detach() {
+    if (this.#closing) return
+    if (this.#options.connectionId === undefined) throw new Error("detach() requires an explicit stable connectionId")
+    if (this.#options.spoolDirectory === undefined) throw new Error("detach() requires an explicit persistent spoolDirectory")
+    this.#preserveSpools = true
+    this.#closing = true
+    if (this.#reconnectTimer !== undefined) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = undefined
+    this.#setState("closed")
+    const physical = this.#physical
+    physical?.pause()
+    physical?.destroy()
+    const frameQueue = this.#physicalFrameQueue
+    try {
+      await frameQueue
+      await Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream)))
+    } finally {
+      physical?.destroy()
+      this.#physical = undefined
+      this.#rejectConnect?.(new SocketductSessionLostError("Reverse connection detached for durable recovery", "CONNECTION_DETACHED"))
+      this.#settleConnect()
+    }
+  }
 
   _writeStream(/** @type {number} */ streamId, /** @type {Buffer} */ data, /** @type {(error?: Error | null) => void} */ callback) {
     const stream = this.#streams.get(streamId)
-    if (stream === undefined || stream.localEnded || stream.state === "closed" || stream.state === "reset") { callback(new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")); return }
+    if (this.#closing || stream === undefined || stream.localEnded || stream.state === "closed" || stream.state === "reset") { callback(new SocketductStreamError("Reverse stream is not writable", "ERR_STREAM_DESTROYED")); return }
     stream.pendingWrite = {data, offset: 0, callback}
     this.#progressPendingWrites()
   }
 
   _endStream(/** @type {number} */ streamId, /** @type {(error?: Error | null) => void} */ callback) {
     const stream = this.#streams.get(streamId)
-    if (stream === undefined || stream.localEnded) { callback(); return }
+    if (this.#closing || stream === undefined || stream.localEnded) { callback(); return }
     stream.localEnded = true
     if (stream.state === "closed") { callback(); return }
+    if (stream.opened && stream.state === "open") stream.state = "half-closed"
     stream.endCallback = callback
-    void this.#pumpStream(stream).catch((error) => this.#finishEnd(stream, asError(error)))
+    void this.#persistStreamState(stream).then(() => this.#pumpStream(stream)).catch((error) => this.#finishEnd(stream, asError(error)))
   }
 
   _destroyStream(/** @type {number} */ streamId, /** @type {Error | null} */ error) {
@@ -275,11 +418,26 @@ export class ReverseGatewayConnection extends EventEmitter {
   }
 
   _resumeReadable(/** @type {number} */ streamId) {
+    void streamId
+  }
+
+  _consumeReadable(/** @type {number} */ streamId, /** @type {number} */ bytes) {
     const stream = this.#streams.get(streamId)
-    if (stream?.pendingReceiveAck === undefined) return
-    const sequence = stream.pendingReceiveAck
-    stream.pendingReceiveAck = undefined
-    this.#ackReceived(stream, sequence)
+    if (stream === undefined || !Number.isSafeInteger(bytes) || bytes <= 0) return
+    let remaining = bytes
+    let acknowledgedSequence = stream.receiveAck
+    while (remaining > 0 && stream.receiveFrames.length > 0) {
+      const frame = /** @type {{sequence: number, remaining: number}} */ (stream.receiveFrames[0])
+      const consumed = Math.min(remaining, frame.remaining)
+      frame.remaining -= consumed
+      remaining -= consumed
+      if (frame.remaining === 0) {
+        acknowledgedSequence = frame.sequence
+        stream.receiveFrames.shift()
+      }
+    }
+    if (remaining !== 0) throw new Error("Reverse client readable accounting underflow")
+    this.#ackReceived(stream, acknowledgedSequence)
   }
 
   #allocateStreamId() {
@@ -322,6 +480,7 @@ export class ReverseGatewayConnection extends EventEmitter {
     physical.setKeepAlive(true, DEFAULT_KEEP_ALIVE_INITIAL_DELAY_MS)
     const decoder = new V3FrameDecoder({maxFrameBytes: Math.max(MAX_CONTROL_BYTES, this.#maxFrameBytes() + 4), maxBufferedBytes: Math.max(MAX_CONTROL_BYTES, this.#maxFrameBytes() + 4) * 2})
     let queue = Promise.resolve()
+    this.#physicalFrameQueue = queue
     let authenticated = false
     let selected = false
     /** @type {Error | undefined} */
@@ -329,14 +488,21 @@ export class ReverseGatewayConnection extends EventEmitter {
     const timer = setTimeout(() => physical.destroy(Object.assign(new Error("Reverse client TLS/auth timeout"), {code: "SOCKETDUCT_AUTH_TIMEOUT"})), this.#options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS)
     timer.unref?.()
     physical.once("secureConnect", () => {
-      const body = encodeV3Control({role: "client", token: this.#options.hub.token, versions: [3], connectionId: this.#connectionId, generation, compression: availableCodecs()})
-      void writeSocket(physical, encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: generation}, body))
-        .catch((error) => physical.destroy(asError(error)))
+      // The attempted generation must survive a crash after AUTH reaches the
+      // hub but before AUTH_OK returns, otherwise a replacement could reuse a
+      // fenced generation after wall-clock rollback.
+      void Promise.all([...this.#streams.values()].map((stream) => this.#persistStreamState(stream))).then(async () => {
+        if (this.#physical !== physical || physical.destroyed || this.#closing) return
+        const body = encodeV3Control({role: "client", token: this.#options.hub.token, versions: [3], connectionId: this.#connectionId, generation, compression: availableCodecs()})
+        await writeSocket(physical, encodeV3Frame({type: V3FrameType.AUTH, streamId: 0, sequence: generation}, body))
+      }).catch((error) => physical.destroy(asError(error)))
     })
     physical.on("data", (chunk) => {
+      if (this.#closing || this.#physical !== physical) return
       physical.pause()
       queue = queue.then(async () => {
         for (const frame of decoder.push(chunk)) {
+          if (this.#closing || this.#physical !== physical) return
           if (frame.type === V3FrameType.AUTH_ERROR || frame.type === V3FrameType.GOAWAY) {
             const detail = decodeV3Control(frame.payload)
             throw connectionError(typeof detail.code === "string" ? detail.code : "CONNECTION_REJECTED")
@@ -348,6 +514,10 @@ export class ReverseGatewayConnection extends EventEmitter {
             authenticated = true
             this.#codec = ZSTD_CODEC
             this.#sendWindowLimit = Math.min(this.#initialWindow(), detail.initialWindow)
+            for (const stream of this.#streams.values()) {
+              stream.sendWindowLimit = Math.min(stream.sendWindowLimit, this.#sendWindowLimit)
+              stream.sendWindow = Math.min(stream.sendWindow, stream.sendWindowLimit)
+            }
             await writeSocket(physical, encodeV3Frame({type: V3FrameType.GATEWAY_SELECT, streamId: 0, sequence: generation}, encodeV3Control(this.#routeIdentityFields())))
             continue
           }
@@ -356,37 +526,28 @@ export class ReverseGatewayConnection extends EventEmitter {
             const detail = decodeV3Control(frame.payload)
             const selection = this.#routeIdentityFields()
             if (detail.generation !== generation || ("gatewayId" in selection ? detail.gatewayId !== selection.gatewayId || Object.hasOwn(detail, "routeClass") : detail.routeClass !== selection.routeClass || Object.hasOwn(detail, "gatewayId"))) throw fatalError("GATEWAY_SELECTION_FAILED")
+            if (typeof detail.resumed !== "boolean") throw fatalError("GATEWAY_SELECTION_FAILED")
             selected = true
-            clearTimeout(timer)
-            this.#physicalConnects += 1
-            this.#reconnectDelay = this.#options.reconnectDelayMs ?? 250
-            this.#setState("ready")
-            logDiagnostic(this.#options.logger, "transport.connected", {
-              generation,
-              attempt: this.#physicalAttempts,
-              ...this.#routeIdentityFields(),
-              physicalConnects: this.#physicalConnects,
-              reconnect: this.#physicalConnects > 1
-            })
-            if (this.#physicalConnects > 1) {
-              logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
-                generation,
-                attempt: this.#reconnectAttempts,
-                ...this.#routeIdentityFields(),
-                physicalConnects: this.#physicalConnects
-              })
+            if (detail.resumed) {
+              clearTimeout(timer)
+              this.#resuming = true
+              await this.#sendResumeManifest(generation)
+            } else if ([...this.#streams.values()].some((stream) => stream.openingSent || stream.opened)) {
+              for (const stream of [...this.#streams.values()]) stream.socket._receiveError(new SocketductSessionLostError("Reverse gateway hub lost the retained stream", "RESUME_SESSION_LOST"))
+              this.#completePhysical(generation, timer)
+            } else {
+              this.#completePhysical(generation, timer)
             }
-            this.#resolveConnect?.()
-            this.#settleConnect()
             continue
           }
-          await this.#handleFrame(frame)
+          await this.#handleFrame(frame, physical)
         }
       }).catch((error) => {
         attemptError = asError(error)
         if (/** @type {{fatal?: unknown}} */ (attemptError).fatal === true) this.#fatal = true
         physical.destroy(attemptError)
       }).finally(() => { if (!physical.destroyed) physical.resume() })
+      this.#physicalFrameQueue = queue
     })
     physical.once("error", (error) => { attemptError = error; if (isFatalTransportError(error)) this.#fatal = true })
     physical.once("close", () => {
@@ -395,8 +556,11 @@ export class ReverseGatewayConnection extends EventEmitter {
         if (this.#physical !== physical) return
         this.#physical = undefined
         this.#codec = undefined
+        this.#resuming = false
+        this.#resumeResults = []
+        this.#resumeNextPage = 0
         if (!this.#closing && !this.#fatal) this.#setState("reconnecting")
-        const lost = new SocketductSessionLostError("Reverse gateway transport was lost; operation outcome may be uncertain", "GATEWAY_DISCONNECTED")
+        const lost = new SocketductSessionLostError("Reverse gateway physical transport was interrupted", "GATEWAY_DISCONNECTED")
         if (!this.#closing) {
           logDiagnostic(this.#options.logger, "transport.disconnected", {
             generation,
@@ -405,10 +569,15 @@ export class ReverseGatewayConnection extends EventEmitter {
             ...errorDiagnostics(attemptError ?? lost, "GATEWAY_DISCONNECTED")
           })
         }
-        for (const stream of [...this.#streams.values()]) stream.socket._receiveError(lost)
+        for (const stream of this.#streams.values()) {
+          stream.sendWindow = stream.sendWindowLimit
+          for (const replay of stream.replay) replay.sent = false
+        }
         if (this.#closing) return
         if (this.#fatal) {
           const terminalError = attemptError ?? lost
+          const terminalCode = /** @type {{code?: unknown}} */ (terminalError).code
+          if (terminalCode === "STALE_GENERATION" || terminalCode === "CONNECTION_REPLACED") this.#preserveSpools = true
           this.#fatalError = terminalError
           this.#setState("closed", terminalError)
           logDiagnostic(this.#options.logger, "transport.failed", {
@@ -419,6 +588,7 @@ export class ReverseGatewayConnection extends EventEmitter {
           })
           this.#rejectConnect?.(terminalError)
           this.#settleConnect()
+          for (const stream of [...this.#streams.values()]) stream.socket._receiveError(terminalError)
           return
         }
         if (this.#warm || this.#options.continuousReconnect !== false) this.#scheduleReconnect(attemptError)
@@ -426,10 +596,26 @@ export class ReverseGatewayConnection extends EventEmitter {
     })
   }
 
-  /** @param {import('../protocol/v3-frame.js').V3Frame} frame - Hub frame. */
-  async #handleFrame(frame) {
+  /** @param {import('../protocol/v3-frame.js').V3Frame} frame - Hub frame. @param {import('node:tls').TLSSocket} physical - Owning physical generation. */
+  async #handleFrame(frame, physical) {
+    if (this.#closing || this.#physical !== physical) return
     if (frame.type === V3FrameType.PING) { await this.#sendControl(V3FrameType.PONG, 0, frame.sequence, {}); return }
     if (frame.type === V3FrameType.PONG) return
+    if (frame.type === V3FrameType.RESUMED) {
+      if (!this.#resuming) throw new Error("Unexpected reverse client RESUMED response")
+      const manifest = decodeV3Control(frame.payload)
+      if (manifest.page !== this.#resumeNextPage || !Array.isArray(manifest.streams)) throw new Error("Invalid reverse client RESUMED response")
+      this.#resumeNextPage += 1
+      this.#resumeResults.push(...manifest.streams.filter((item) => typeof item === "object" && item !== null))
+      if (manifest.final !== true) return
+      for (const item of this.#resumeResults) await this.#applyResumeResult(item)
+      if (this.#closing || this.#physical !== physical) return
+      this.#resumeResults = []
+      this.#resumeNextPage = 0
+      this.#resuming = false
+      this.#completePhysical(this.#generation)
+      return
+    }
     const stream = this.#streams.get(frame.streamId)
     if (stream === undefined) {
       if (frame.type !== V3FrameType.CLOSE && frame.type !== V3FrameType.RESET) await this.#sendControl(V3FrameType.RESET, frame.streamId, 0, {code: "UNKNOWN_STREAM"})
@@ -440,13 +626,16 @@ export class ReverseGatewayConnection extends EventEmitter {
       if (stream.state !== "opening" || frame.sequence !== 0 || detail.identifier !== stream.identifier || !validPeerWindow(detail.initialWindow)) throw new Error("Invalid reverse OPENED response")
       stream.sendWindowLimit = Math.min(stream.sendWindowLimit, detail.initialWindow)
       stream.sendWindow = Math.min(stream.sendWindow, stream.sendWindowLimit)
-      stream.state = "open"
+      stream.state = stream.localEnded ? "half-closed" : "open"
+      stream.opened = true
       logDiagnostic(this.#options.logger, "virtual_stream.opened", {
         streamId: stream.id,
         generation: this.#generation,
         ...this.#routeIdentityFields(),
         recovered: false
       })
+      await this.#persistStreamState(stream)
+      if (this.#closing || this.#physical !== physical) return
       stream.socket._markConnected()
       this.#progressPendingWrites()
       await this.#pumpStream(stream)
@@ -455,11 +644,11 @@ export class ReverseGatewayConnection extends EventEmitter {
     if (frame.type === V3FrameType.DATA) {
       if (stream.remoteEnded) throw new Error("Reverse client received DATA after END")
       const data = await decodeV3Data(frame, this.#codec, this.#options.compressionLimits)
+      if (this.#closing || this.#physical !== physical) return
       if (data.length === 0 || data.length > this.#maxFrameBytes() || frame.sequence !== stream.receiveSequence + data.length || frame.sequence - stream.receiveAck > this.#initialWindow()) throw new Error("Invalid reverse client DATA sequence or window")
       stream.receiveSequence = frame.sequence
-      const canContinue = stream.socket._receive(data)
-      if (canContinue) this.#ackReceived(stream, frame.sequence)
-      else stream.pendingReceiveAck = frame.sequence
+      stream.receiveFrames.push({sequence: frame.sequence, remaining: data.length})
+      stream.socket._receive(data)
       return
     }
     if (frame.type === V3FrameType.ACK) { this.#acknowledge(stream, frame.sequence); return }
@@ -467,12 +656,15 @@ export class ReverseGatewayConnection extends EventEmitter {
     if (frame.type === V3FrameType.END) {
       if (stream.remoteEnded || frame.sequence !== stream.receiveSequence) throw new Error("Invalid reverse client END")
       stream.remoteEnded = true
+      await this.#persistStreamState(stream)
+      if (this.#closing || this.#physical !== physical) return
       stream.socket._receiveEnd()
       return
     }
     if (frame.type === V3FrameType.CLOSE) {
       if (frame.sequence !== stream.receiveSequence) throw new Error("Invalid reverse client CLOSE")
       await this.#sendControl(V3FrameType.CLOSE, stream.id, stream.transmittedSequence, {})
+      if (this.#closing || this.#physical !== physical) return
       stream.state = "closed"
       logDiagnostic(this.#options.logger, "virtual_stream.closed", {
         streamId: stream.id,
@@ -496,6 +688,105 @@ export class ReverseGatewayConnection extends EventEmitter {
     throw new Error("Unsupported reverse client frame")
   }
 
+  /** Sends the client half of the paired reverse-stream resume manifest. */
+  async #sendResumeManifest(/** @type {number} */ generation) {
+    const activeStreams = [...this.#streams.values()]
+    await Promise.all(activeStreams.map((stream) => this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream)))))
+    const streams = activeStreams.filter((stream) => this.#streams.get(stream.id) === stream).map((stream) => ({
+      streamId: stream.id,
+      identifier: stream.identifier,
+      clientToGatewaySequence: stream.sendSequence,
+      clientToGatewayAck: stream.sendAck,
+      // A replacement cannot inherit the dead VirtualSocket's process-only
+      // readable buffer. Ask the surviving gateway to replay above durable ACK.
+      gatewayToClientSequence: stream.recoveredObject ? stream.receiveAck : stream.receiveSequence,
+      gatewayToClientAck: stream.receiveAck,
+      localEnded: stream.localEnded,
+      remoteEnded: stream.remoteEnded
+    }))
+    this.#resumeResults = []
+    this.#resumeNextPage = 0
+    const pageCount = Math.max(1, Math.ceil(streams.length / MANIFEST_PAGE_STREAMS))
+    for (let page = 0; page < pageCount; page += 1) {
+      await this.#sendControl(V3FrameType.RESUME, 0, generation, {
+        page,
+        final: page === pageCount - 1,
+        streams: streams.slice(page * MANIFEST_PAGE_STREAMS, (page + 1) * MANIFEST_PAGE_STREAMS)
+      })
+    }
+  }
+
+  /** @param {unknown} value - Hub resume result. */
+  async #applyResumeResult(value) {
+    if (typeof value !== "object" || value === null) throw new Error("Invalid reverse client resume result")
+    const result = /** @type {{streamId?: unknown, status?: unknown, clientToGatewaySequence?: unknown, clientToGatewayAck?: unknown, gatewayToClientSequence?: unknown, gatewayToClientAck?: unknown, clientEnded?: unknown, gatewayEnded?: unknown, opened?: unknown, code?: unknown}} */ (value)
+    if (!Number.isInteger(result.streamId)) throw new Error("Invalid reverse client resume stream ID")
+    const stream = this.#streams.get(/** @type {number} */ (result.streamId))
+    if (stream === undefined) return
+    if (result.status !== "resumed") {
+      const code = typeof result.code === "string" ? result.code : "RESUME_REJECTED"
+      stream.socket._receiveError(new SocketductSessionLostError("Reverse gateway stream could not be resumed", code))
+      return
+    }
+    const clientToGatewaySequence = /** @type {number} */ (result.clientToGatewaySequence)
+    const clientToGatewayAck = /** @type {number} */ (result.clientToGatewayAck)
+    const gatewayToClientSequence = /** @type {number} */ (result.gatewayToClientSequence)
+    const gatewayToClientAck = /** @type {number} */ (result.gatewayToClientAck)
+    const validClientToGatewayBoundary = clientToGatewaySequence === stream.sendAck || stream.replay.some((chunk) => chunk.sequence === clientToGatewaySequence)
+    if (!Number.isSafeInteger(clientToGatewaySequence) || clientToGatewaySequence < stream.sendAck || clientToGatewaySequence > stream.sendSequence || !Number.isSafeInteger(clientToGatewayAck) || clientToGatewayAck < stream.sendAck || clientToGatewayAck > clientToGatewaySequence || !validClientToGatewayBoundary || !Number.isSafeInteger(gatewayToClientSequence) || gatewayToClientSequence !== stream.receiveSequence || !Number.isSafeInteger(gatewayToClientAck) || gatewayToClientAck < stream.receiveAck || gatewayToClientAck > gatewayToClientSequence || typeof result.clientEnded !== "boolean" || typeof result.gatewayEnded !== "boolean" || typeof result.opened !== "boolean") throw new Error("Invalid reverse client resume positions")
+    this.#acknowledge(stream, clientToGatewayAck)
+    stream.transmittedSequence = clientToGatewayAck
+    stream.receiveAck = gatewayToClientAck
+    stream.sendWindow = Math.max(0, stream.sendWindowLimit - (clientToGatewaySequence - clientToGatewayAck))
+    for (const chunk of stream.replay) chunk.sent = chunk.sequence <= clientToGatewaySequence
+    stream.endSent = /** @type {boolean} */ (result.clientEnded)
+    if (result.gatewayEnded === true) {
+      stream.remoteEndPending = stream.recoveredObject || !stream.remoteEnded
+      stream.remoteEnded = true
+    }
+    if (result.opened === true) {
+      stream.opened = true
+      if (stream.state === "opening") stream.state = stream.localEnded ? "half-closed" : "open"
+    }
+    stream.openingSent = true
+    stream.recoveredObject = false
+    await this.#persistStreamState(stream)
+  }
+
+  /** Marks one authenticated/selected physical generation ready. */
+  #completePhysical(/** @type {number} */ generation, /** @type {ReturnType<typeof setTimeout> | undefined} */ timer = undefined) {
+    if (timer !== undefined) clearTimeout(timer)
+    this.#physicalConnects += 1
+    this.#reconnectDelay = this.#options.reconnectDelayMs ?? 250
+    this.#setState("ready")
+    logDiagnostic(this.#options.logger, "transport.connected", {
+      generation,
+      attempt: this.#physicalAttempts,
+      ...this.#routeIdentityFields(),
+      physicalConnects: this.#physicalConnects,
+      reconnect: this.#physicalConnects > 1
+    })
+    if (this.#physicalConnects > 1) {
+      logDiagnostic(this.#options.logger, "transport.reconnect_succeeded", {
+        generation,
+        attempt: this.#reconnectAttempts,
+        ...this.#routeIdentityFields(),
+        physicalConnects: this.#physicalConnects
+      })
+    }
+    this.#resolveConnect?.()
+    this.#settleConnect()
+    for (const stream of this.#streams.values()) {
+      if (stream.state !== "opening") stream.socket._markConnected()
+      if (stream.remoteEndPending) {
+        stream.remoteEndPending = false
+        stream.socket._receiveEnd()
+      }
+      void this.#pumpStream(stream).catch((error) => stream.socket._receiveError(asError(error)))
+    }
+    this.#progressPendingWrites()
+  }
+
   /** @param {ReverseClientStream} stream - Stream. */
   async #pumpStream(stream) {
     if (stream.pumping || stream.state === "opening" || !this.#streams.has(stream.id) || this.#state !== "ready") return
@@ -516,7 +807,12 @@ export class ReverseGatewayConnection extends EventEmitter {
       if (stream.localEnded && !stream.endSent && stream.replay.every((chunk) => chunk.sent)) {
         stream.endSent = true
         stream.state = "half-closed"
-        await this.#sendControl(V3FrameType.END, stream.id, stream.sendSequence, {})
+        const delivered = await this.#sendControl(V3FrameType.END, stream.id, stream.sendSequence, {})
+        if (!delivered) {
+          stream.endSent = false
+          return
+        }
+        await this.#persistStreamState(stream)
         this.#finishEnd(stream)
       }
     } finally { stream.pumping = false }
@@ -533,8 +829,7 @@ export class ReverseGatewayConnection extends EventEmitter {
         if (available <= 0) return
         const chunk = Buffer.from(pending.data.subarray(pending.offset, Math.min(pending.data.length, pending.offset + available)))
         try {
-          if (this.#options.aggregateBudget?.reserveMemory !== undefined) this.#options.aggregateBudget.reserveMemory(chunk.length)
-          else this.#options.aggregateBudget?.reserveData(chunk.length)
+          this.#options.aggregateBudget?.reserveData(chunk.length)
         } catch (error) {
           this.#finishWrite(stream, asError(error))
           return
@@ -544,11 +839,19 @@ export class ReverseGatewayConnection extends EventEmitter {
         stream.replay.push({sequence: stream.sendSequence, data: chunk, sent: false})
         stream.bufferedBytes += chunk.length
         this.#bufferedBytes += chunk.length
+        stream.spoolReservedBytes += chunk.length
+        this.#spoolBytes += chunk.length
+        await this.#queueSpoolOperation(stream, async () => {
+          await this.#spool.appendChunk({sessionId: stream.identifier, ownerId: "reverse-client-v3", sequence: stream.sendSequence, data: chunk})
+          await this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream))
+        })
       }
       await this.#pumpStream(stream)
       if (pending.offset === pending.data.length && stream.pendingWrite === pending) this.#finishWrite(stream)
     } catch (error) {
-      this.#finishWrite(stream, asError(error))
+      const failure = asError(error)
+      this.#finishWrite(stream, failure)
+      stream.socket._receiveError(failure)
     } finally {
       stream.progressingWrite = false
       this.#progressPendingWrites()
@@ -601,10 +904,10 @@ export class ReverseGatewayConnection extends EventEmitter {
     if (!this.#streams.delete(stream.id)) return
     this.#bufferedBytes = Math.max(0, this.#bufferedBytes - stream.bufferedBytes)
     this.#options.aggregateBudget?.releaseMemory(stream.bufferedBytes)
-    if (this.#options.aggregateBudget?.reserveMemory === undefined) this.#options.aggregateBudget?.releaseSpool(stream.bufferedBytes)
     stream.replay = []
     stream.bufferedBytes = 0
     this.#finishWrite(stream, pendingWriteError)
+    if (!this.#preserveSpools) this.#trackSpoolCleanup(stream)
     this.#progressPendingWrites()
   }
 
@@ -619,8 +922,15 @@ export class ReverseGatewayConnection extends EventEmitter {
     stream.bufferedBytes = Math.max(0, stream.bufferedBytes - released)
     this.#bufferedBytes = Math.max(0, this.#bufferedBytes - released)
     this.#options.aggregateBudget?.releaseMemory(released)
-    if (this.#options.aggregateBudget?.reserveMemory === undefined) this.#options.aggregateBudget?.releaseSpool(released)
     stream.sendWindow = Math.min(stream.sendWindowLimit, stream.sendWindow + delta)
+    void this.#queueSpoolOperation(stream, async () => {
+      await this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream))
+      await this.#spool.truncateAcked(stream.identifier, sequence)
+      if (released > stream.spoolReservedBytes) throw new Error("Reverse client spool budget release underflow")
+      stream.spoolReservedBytes -= released
+      this.#spoolBytes = Math.max(0, this.#spoolBytes - released)
+      this.#options.aggregateBudget?.releaseSpool(released)
+    }).catch((error) => stream.socket._receiveError(asError(error)))
     this.#progressPendingWrites()
     void this.#pumpStream(stream).catch((error) => stream.socket._receiveError(asError(error)))
   }
@@ -636,7 +946,9 @@ export class ReverseGatewayConnection extends EventEmitter {
   #ackReceived(stream, sequence) {
     if (sequence <= stream.receiveAck) return
     stream.receiveAck = sequence
-    void this.#sendControl(V3FrameType.ACK, stream.id, sequence, {}).catch(() => {})
+    void this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream)))
+      .then(() => this.#sendControl(V3FrameType.ACK, stream.id, sequence, {}).catch(() => {}))
+      .catch((error) => stream.socket._receiveError(asError(error)))
   }
 
   /** @param {number} type - Type. @param {number} streamId - Stream. @param {number} sequence - Sequence. @param {Record<string, unknown>} body - Body. */
@@ -674,6 +986,76 @@ export class ReverseGatewayConnection extends EventEmitter {
     }
   }
 
+  /** @param {ReverseClientStream} stream - Durable stream state. */
+  #recoveryState(stream) {
+    return {
+      version: 3,
+      role: "reverse-client",
+      connectionId: this.#connectionId,
+      generation: this.#generation,
+      ...this.#routeIdentityFields(),
+      streamId: stream.id,
+      identifier: stream.identifier,
+      name: stream.name,
+      target: stream.target,
+      state: stream.state,
+      opened: stream.opened,
+      openingSent: stream.openingSent,
+      sendSequence: stream.sendSequence,
+      sendAck: stream.sendAck,
+      receiveSequence: stream.receiveSequence,
+      receiveAck: stream.receiveAck,
+      localEnded: stream.localEnded,
+      remoteEnded: stream.remoteEnded,
+      endSent: stream.endSent
+    }
+  }
+
+  /** @param {ReverseClientStream} stream - Durable stream state. */
+  async #persistStreamState(stream) {
+    await this.#queueSpoolOperation(stream, () => this.#spool.writeRecoveryState(stream.identifier, this.#recoveryState(stream)))
+  }
+
+  /** @param {ReverseClientStream} stream - Spool owner. @param {() => Promise<void>} operation - Serialized durable operation. */
+  async #queueSpoolOperation(stream, operation) {
+    const next = stream.spoolQueue.then(async () => {
+      await stream.spoolReady
+      await operation()
+    })
+    stream.spoolQueue = next.catch(() => {})
+    await next
+  }
+
+  /** @param {ReverseClientStream} stream - Terminal stream. */
+  async #removeSpool(stream) {
+    if (stream.spoolRemovalPromise === undefined) {
+      stream.spoolRemovalPromise = this.#queueSpoolOperation(stream, async () => {
+        await this.#spool.remove(stream.identifier)
+        const removed = stream.spoolReservedBytes
+        stream.spoolReservedBytes = 0
+        this.#spoolBytes = Math.max(0, this.#spoolBytes - removed)
+        this.#options.aggregateBudget?.releaseSpool(removed)
+      })
+    }
+    await stream.spoolRemovalPromise
+  }
+
+  /** @param {ReverseClientStream} stream - Terminal stream. */
+  #trackSpoolCleanup(stream) {
+    const removal = stream.ownsSpool
+      ? this.#removeSpool(stream)
+      : stream.spoolReady.then(() => stream.ownsSpool ? this.#removeSpool(stream) : undefined)
+    const task = removal.catch((error) => {
+      if (!stream.spoolCleanupFailureRecorded) {
+        stream.spoolCleanupFailureRecorded = true
+        this.#spoolCleanupFailures += 1
+      }
+      throw error
+    })
+    this.#spoolCleanupTasks.add(task)
+    void task.catch(() => {}).finally(() => this.#spoolCleanupTasks.delete(task))
+  }
+
   #settleConnect() { this.#connectPromise = undefined; this.#resolveConnect = undefined; this.#rejectConnect = undefined }
   #setState(/** @type {'configured' | 'connecting' | 'ready' | 'reconnecting' | 'closed'} */ state, /** @type {Error | undefined} */ error = undefined) { if (this.#state === state) return; this.#state = state; this.emit("stateChange", state, error) }
   /** @returns {{gatewayId: string} | {routeClass: string}} Stable physical route identity. */
@@ -705,9 +1087,76 @@ function validateOptions(options) {
   positiveInteger(options.maxStreams, "maxStreams", DEFAULT_MAX_STREAMS)
   positiveInteger(options.maxStreamBufferBytes, "maxStreamBufferBytes", DEFAULT_STREAM_BUFFER_BYTES)
   positiveInteger(options.maxConnectionBufferBytes, "maxConnectionBufferBytes", DEFAULT_CONNECTION_BUFFER_BYTES)
+  if (options.spoolDirectory !== undefined && (typeof options.spoolDirectory !== "string" || options.spoolDirectory.length === 0)) throw new TypeError("spoolDirectory must be a non-empty string")
+  positiveInteger(options.maxAgeMs, "maxAgeMs", 24 * 60 * 60 * 1000)
   if (options.initialGeneration !== undefined && (!Number.isSafeInteger(options.initialGeneration) || options.initialGeneration < 0)) throw new RangeError("initialGeneration must be a non-negative safe integer")
 }
 
+/**
+ * @param {Record<string, unknown>} value - Parsed durable state.
+ * @param {{connectionId: string, identifier: string, target: {host: string, port: number}, selection: {gatewayId: string} | {routeClass: string}, initialWindow: number, sessionName?: string}} expected - Caller-owned recovery identity.
+ * @returns {ReverseClientRecoveryState} Validated state.
+ */
+function validateRecoveryState(value, expected) {
+  const state = /** @type {Partial<ReverseClientRecoveryState>} */ (value)
+  const sequences = [state.generation, state.streamId, state.sendSequence, state.sendAck, state.receiveSequence, state.receiveAck]
+  const validSequences = sequences.every((sequence) => Number.isSafeInteger(sequence) && /** @type {number} */ (sequence) >= 0)
+  const validTarget = state.target?.host === expected.target.host && state.target?.port === expected.target.port
+  const expectedState = state.opened === true ? (state.localEnded === true ? "half-closed" : "open") : "opening"
+  const selectorMatches = "gatewayId" in expected.selection
+    ? state.gatewayId === expected.selection.gatewayId && !Object.hasOwn(state, "routeClass")
+    : state.routeClass === expected.selection.routeClass && !Object.hasOwn(state, "gatewayId")
+  if (
+    state.version !== 3
+    || state.role !== "reverse-client"
+    || state.connectionId !== expected.connectionId
+    || state.identifier !== expected.identifier
+    || !validSequences
+    || state.generation === 0
+    || state.generation === Number.MAX_SAFE_INTEGER
+    || state.streamId === 0
+    || /** @type {number} */ (state.streamId) % 2 === 0
+    || /** @type {number} */ (state.streamId) > 0xffff_fffd
+    || typeof state.name !== "string"
+    || state.name.length === 0
+    || state.name.length > 256
+    || !validTarget
+    || !selectorMatches
+    || typeof state.opened !== "boolean"
+    || state.openingSent !== true
+    || typeof state.localEnded !== "boolean"
+    || typeof state.remoteEnded !== "boolean"
+    || typeof state.endSent !== "boolean"
+    || (state.endSent && !state.localEnded)
+    || (state.endSent && state.opened !== true)
+    || (state.remoteEnded && state.opened !== true)
+    || (state.opened !== true && (/** @type {number} */ (state.sendSequence) > 0 || /** @type {number} */ (state.receiveSequence) > 0))
+    || state.state !== expectedState
+    || /** @type {number} */ (state.sendAck) > /** @type {number} */ (state.sendSequence)
+    || /** @type {number} */ (state.receiveAck) > /** @type {number} */ (state.receiveSequence)
+    || /** @type {number} */ (state.receiveSequence) - /** @type {number} */ (state.receiveAck) > expected.initialWindow
+    || (expected.sessionName !== undefined && state.name !== expected.sessionName)
+  ) throw new Error("Invalid reverse client recovery identity, selector, lifecycle, or sequence state")
+  return /** @type {ReverseClientRecoveryState} */ (state)
+}
+
+/**
+ * @param {ReverseClientRecoveryState} state - Validated durable state.
+ * @param {import('../spool/spool-file.js').SpoolChunk[]} chunks - Durable chunks.
+ * @param {number} maxBytes - Per-stream byte bound.
+ * @param {number} maxFrameBytes - Per-chunk frame bound.
+ */
+function validateRecoveredChunks(state, chunks, maxBytes, maxFrameBytes) {
+  let sequence = state.sendAck
+  let bytes = 0
+  for (const chunk of chunks) {
+    bytes += chunk.data.length
+    if (chunk.data.length === 0 || chunk.data.length > maxFrameBytes || !Number.isSafeInteger(sequence + chunk.data.length) || chunk.sequence !== sequence + chunk.data.length || chunk.sequence > state.sendSequence) throw new Error("Invalid reverse client recovery chunk sequence")
+    sequence = chunk.sequence
+  }
+  if (sequence !== state.sendSequence || bytes > maxBytes) throw new Error("Invalid or oversized reverse client recovery replay state")
+}
+
 /** @param {VirtualSocket} socket - Socket. @param {(error: Error | null, socket: VirtualSocket) => void} callback - Callback. */
 function installCallback(socket, callback) {
   let settled = false