socketduct 0.1.20 → 0.1.22

package/changelog.d/20260925180000-manual-ack-durable-admission.md

@@ -0,0 +1 @@
+Reverse clients can now durably admit complete writes, manually acknowledge application-committed receive bytes, and recover transport-set streams by stable identifier alone.

package/changelog.d/20260928120416-reverse-gateway-spool-directory.md

@@ -0,0 +1,3 @@
+# Outbound reverse gateway spool directory environment variable
+
+The standalone outbound reverse gateway runtime now accepts `SOCKETDUCT_SPOOL_DIRECTORY`, which points the gateway's durable target-output spool at an operator-chosen persistent path. The default remains the process temporary directory, so containerized gateways can move the bounded spool behind exactly-once resume replay onto a host volume instead of the container's ephemeral, size-bounded `/tmp`. The variable is accepted only in `reverse-gateway` mode and is rejected in every other mode.

package/changelog.d/20260928124500-critical-reserve-bound-test.md

@@ -0,0 +1,3 @@
+# Bound the compressed-log critical reserve test to a coverable charge
+
+The compressed-log queue-pressure test asserted that a critical disconnect record is accepted while a 4096-byte queue holds a 1024-byte critical reserve, but the record's conservative charge (line bytes × 3 + 128) exceeds the reserve, so the writer correctly dropped it and the test failed on every run. Accepted log sequences are append-only and cannot be evicted without tearing the durable journal, so the test now reserves 2048 bytes — covering the critical record's charge — and the logging docs state the reserve sizing bound explicitly.

package/docs/logging.md

@@ -28,7 +28,11 @@ SOCKETDUCT_LOG_COMPRESSION_LEVEL=19
 Those values are the defaults. Reaching the uncompressed frame limit starts a
 flush immediately. Flush deadlines are measured from the oldest queued work and
 are never extended by later records; critical lifecycle, security, and resume
-events use the shorter deadline and may use the reserved queue capacity.
+events use the shorter deadline and may use the reserved queue capacity. A
+critical record is guaranteed acceptance only while its conservative charge
+(line bytes × 3 + 128) fits the reserve, because accepted sequences are
+append-only and can never be evicted from the durable journal; size the
+reserve for the largest critical record you must retain under queue pressure.
 Segment size, age, and directory quota are bounded independently. Invalid or mutually
 inconsistent values stop startup.
 The former `SOCKETDUCT_LOG_MAX_FILE_BYTES` and `SOCKETDUCT_LOG_MAX_FILES`

package/docs/protocol.md

@@ -133,9 +133,9 @@ each per-stream `RESUMED` result, and only then admits replay. Senders replay
 durable raw chunks strictly above the high-water sequence while retaining
 unacknowledged chunks and charging their outstanding bytes to the new window.
 A DATA frame that entered a failed physical socket but did not reach the
-logical receiver is therefore replayed; a byte already buffered by the receiver
-is not delivered twice. The target socket is never reopened and the application
-request is never recreated as a new stream.
+logical receiver is therefore replayed; a byte durably acknowledged by the
+receiver is not delivered twice. The target socket is never reopened and the
+application request is never recreated as a new stream.
 
 Reverse send replay is persisted before transmission on both the Server3 client
 and outbound gateway. ACKs truncate those private temporary spools. Missing
@@ -151,6 +151,24 @@ returned to the application; merely buffering them below the readable
 high-water mark is process-local and does not make them safe across replacement.
 It never emits `OPEN`.
 
+Reverse sockets default to this automatic application-consumption ACK. With the
+persisted `manualReceiveAck` stream flag, consumption only advances an
+application-delivered counter. An explicit byte count is valid only through
+that counter. Socketduct atomically persists the resulting cumulative
+`receiveAck` before emitting the wire `ACK`; persistence failure emits no ACK
+and terminates the stream. ACK positions are application-byte positions and may
+split a stored DATA chunk, in which case only its suffix remains replayable.
+
+The reverse client also supports an all-or-nothing durable application
+admission. It preflights the complete operation against current stream,
+connection, and aggregate budgets, splits it into ordinary bounded DATA chunks,
+writes the complete raw batch, and writes recovery metadata containing the new
+`sendSequence` last. No DATA becomes send-eligible until that commit succeeds.
+An interrupted pre-commit batch is an uncommitted tail: live retry replaces it,
+and replacement recovery discards it using the older committed sequence. After
+commit, ordinary flow-control, compression, transmission, ACK, replay, and END
+ordering are unchanged.
+
 Only the reverse client is replaceable in this protocol boundary. The same hub
 process and retained bridge, outbound gateway process, and original target TCP
 socket must survive. Hub restart reconstruction, gateway process/socket-keeper

package/docs/reverse-gateway.md

@@ -116,6 +116,22 @@ per-stream and per-connection ceilings, and released connection capacity rotates
 among streams with pending writes. The ceilings limit retained flow-control state,
 not the size of one application write.
 
+Reverse `VirtualSocket` instances also expose `writeDurable(bytes)` for one
+complete serialized application operation such as an HTTP request. Unlike an
+ordinary streaming `write()`, it requires the whole operation to fit the
+current per-stream, per-connection, and transport-set retained/spool budgets.
+Socketduct reserves the complete byte count, replaces any uncommitted spool
+tail, writes every frame-sized raw chunk, and commits the new send sequence
+before resolving. Only then can the first byte be transmitted. Limit rejection
+uses `SOCKETDUCT_DURABLE_WRITE_LIMIT` (or an applicable `SOCKETDUCT_SET_*`
+limit), and persistence failure uses
+`SOCKETDUCT_DURABLE_WRITE_PERSISTENCE`; both admit zero bytes and leave the
+socket available for retry. Each successful repeated call is a distinct
+operation. A physical write failure after admission uses normal durable replay.
+Destroy/close rejects with `ERR_STREAM_DESTROYED`, while detach finishes an
+admission already committing, rejects queued admissions with
+`SOCKETDUCT_CONNECTION_DETACHED`, and preserves committed spool state.
+
 Compression and decompression use Node's asynchronous native zstd APIs, whose
 work runs in the libuv worker pool across CPU cores. The hub keeps registration
 and stream ownership on one deterministic event loop instead of splitting its
@@ -150,10 +166,17 @@ Reverse replay state is bounded per stream and connection and stored in private
 spool directories. ACKed chunks are truncated, and terminal close/reset removes
 the spool. `status().spoolBytes` reports retained durable payload. Reverse-client
 replacement requires the same explicit `connectionId`, an explicit persistent
-`spoolDirectory`, and the same stream identifier, name, target, and one original
-selector (`gatewayId` or `routeClass`). Register every stream with
-`registerRecoveredConnection({...options, recover: true})` before `connect()`;
-registration synchronously rejects missing, expired, corrupt, wrong-owner,
+`spoolDirectory`, and the same stream identifier. A direct
+`ReverseGatewayConnection` may still register the stored name, target, and
+selector with `registerRecoveredConnection({...options, recover: true})` before
+`connect()`. A transport set can instead call
+`recoverConnection({identifier})` before `start()`; it validates every
+configured member namespace and restores the stored target, name, receive-ACK
+mode, and original selector without selecting a live path. No match fails with
+`SOCKETDUCT_RECOVERY_NOT_FOUND`; more than one match fails with
+`SOCKETDUCT_RECOVERY_AMBIGUOUS`. Corrupt, expired, or wrong-owner state fails
+rather than being treated as absent. Legacy selector-based recovery remains
+supported. Registration synchronously rejects missing, expired, corrupt, wrong-owner,
 mismatched, noncontiguous, or oversized state before any network attempt. The
 stored generation is advanced and persisted before AUTH, recovered outbound
 replay starts above the gateway high-water position, and inbound delivery starts
@@ -165,6 +188,23 @@ repair derivable usage accounting after an abrupt process loss; structural,
 identity, sequence, quota, and non-tail corruption still fail closed. Recovery
 never sends `OPEN`.
 
+The default remains automatic receive ACK. A reverse stream opts into durable
+application ownership with `manualReceiveAck: true`. Socketduct then records
+bytes delivered to the application but does not advance the durable ACK until
+`await socket.acknowledgeReceive(bytes)` succeeds after the parser or journal
+commit. Counts are application bytes and may end inside a DATA frame; sender
+memory and spool state retain only the unacknowledged suffix. Calls serialize
+and return the cumulative receive sequence. Non-positive counts or counts above
+delivered, not-yet-acknowledged bytes fail with
+`SOCKETDUCT_INVALID_RECEIVE_ACK`; a repeated successful call acknowledges new
+bytes rather than duplicating the previous call. Calling without opting in
+fails with `SOCKETDUCT_MANUAL_ACK_DISABLED`. Persistence failure rejects the
+call and terminates the stream before a wire ACK advances. Calls after socket
+close reject with `ERR_STREAM_DESTROYED`, and calls after detach reject with
+`SOCKETDUCT_CONNECTION_DETACHED`; an ACK already admitted is persisted before
+detach completes. Recovery preserves manual mode so a replacement cannot
+silently fall back to automatic ACK.
+
 The default reverse spool is under `/tmp`, and the sample reverse-gateway
 Compose mounts `/tmp` as tmpfs. Those defaults do not survive a container or
 host replacement. A caller claiming process/container recovery must supply a
@@ -258,9 +298,17 @@ SOCKETDUCT_REVERSE_TOKEN='<secret>' \
 SOCKETDUCT_REVERSE_HUB_CA_FILE=/certs/hub-ca.crt \
 SOCKETDUCT_REVERSE_HUB_SERVERNAME=server3.example.net \
 SOCKETDUCT_TARGET_ALLOWLIST=docker-a:2375 \
+SOCKETDUCT_SPOOL_DIRECTORY=/var/lib/socketduct/spool \
 node src/index.js
 ```
 
+`SOCKETDUCT_SPOOL_DIRECTORY` is reverse-gateway-only and points the gateway's
+durable target-output spool — the bounded store behind exactly-once resume
+replay — at an operator-chosen path. Without it the spool lives under the
+process temporary directory, which is ephemeral and size-bounded inside a
+container; set it to a persistent host mount so spool capacity and retention
+do not depend on container lifetime. The runtime rejects it in every other mode.
+
 The namespace/default-route configuration remains outside Socketduct. Each
 gateway registration represents one exact target server and WAN class;
 Socketduct does not aggregate away either identity. Socketduct needs no inbound
@@ -299,10 +347,11 @@ Callers cannot override either selection per open. Reverse streams remain
 sticky to their selected gateway/target but resume transparently after a
 transient physical transport replacement.
 
-For process replacement, call `recoverConnection()` before `start()` with
-exactly the socket's immutable original selector: `gatewayId` for an exact set
-or `routeClass` for a route-class set. Recovery derives the original member
-identity and spool namespace and never falls back to or probes a sibling.
+For process replacement, call `recoverConnection({identifier})` before
+`start()`. Recovery locates exactly one configured durable member from the
+stable stream identifier, derives its original identity and spool namespace,
+and never falls back to or probes a sibling. The older explicit `gatewayId` or
+`routeClass` form remains available when the caller already stores it.
 
 The socket is returned immediately and waits inside Socketduct until the set
 reaches minimum readiness. New sockets rotate equally across ready members and

package/docs/running.md

@@ -213,6 +213,7 @@ inspect its ordered aggregate causes or privacy-safe per-member status codes.
 No extra physical member is created. Configure the set-wide buffer/spool/queue
 limits for the whole process rather than multiplying a desired budget by
 gateway count.
-For process replacement, call `recoverConnection()` with exactly each stream's
-original gateway ID or reverse route class before `start()`; see the sequence in
+For process replacement, call `recoverConnection({identifier})` for each durable
+stream before `start()`; Socketduct restores its original configured member from
+private spool metadata. See the sequence in
 [Node-compatible socket API design](socket-api.md#multiplexedsocketducttransportset-multi-gateway-v3-api).

package/docs/session-lifecycle.md

@@ -37,6 +37,22 @@ socket. That ACK covers bytes returned to the application, not bytes merely
 buffered in the dead process. An orderly `detach()` drains already-queued frame
 handling before its final durable snapshot and handoff.
 
+Applications that need parser/journal durability opt a reverse stream into
+manual receive ACK. Bytes may be read and parsed without changing the durable
+ACK; after the application state commit, an explicit application-byte count is
+persisted and then sent cumulatively. Invalid, duplicate-overrun, post-close,
+and post-detach calls fail without advancing it. A persistence failure is
+terminal because Socketduct cannot prove that application and transport state
+agree.
+
+A complete serialized request can use durable admission instead of ordinary
+streaming write. The whole request must fit current configured retained/spool
+limits. Its chunks and final send sequence commit before any chunk is eligible
+for transmission. Limit or persistence failure admits zero bytes, so the caller
+may retry the same operation; success admits it once, and a repeated successful
+call is a new operation. Detach waits for a committing admission and preserves
+it, but rejects queued admissions that have not started.
+
 Hub process reconstruction, gateway process or file-descriptor transfer, and
 target reopen/retry are unsupported. A replacement gateway has no live target
 sockets and therefore completes retained-state registration with an empty
@@ -50,6 +66,12 @@ resume reset and a typed session-loss error, while retained siblings continue.
 Only bytes above the peer's received high-water sequence are replayed; spool
 cleanup remains governed by its acknowledgement.
 
+Replacement transport sets look up a durable stream by its stable identifier
+across configured private spool namespaces before starting. Exactly one owner is
+required. Missing and ambiguous identities fail closed; target, name, original
+selector, and manual-ACK mode come from validated durable metadata rather than
+ephemeral caller state.
+
 ## States
 
 ```text

package/docs/socket-api.md

@@ -218,36 +218,33 @@ socket with ordinary `tls.connect` target options such as `servername`, `ca`,
 the callback, which runs exactly once only after `secureConnect` or failure.
 Both methods count only completed member assignments and preserve stream
 stickiness. Every returned raw or TLS socket exposes enumerable `gatewayId` and
-`routeClass` allocation metadata. Only the configured identity is set. Persist
-an exact set's immutable original selector after connection: `gatewayId` for a
-gateway member or `routeClass` for a reverse member. A replacement uses that
-selector to recover the stream on its original member without running selection
-again.
+`routeClass` allocation metadata. Only the configured identity is set. The
+metadata remains useful for diagnostics, but replacement recovery no longer
+requires the caller to persist it.
 
 Process-replacement recovery is deliberately separate from ordinary selection.
 First detach the old set when an orderly handoff is possible. Construct the
 replacement with the same base `connectionId`, spool directory, and configured
-member endpoints. Then register each durable stream with exactly its original
-`gatewayId` or `routeClass` before calling `start()`:
+member endpoints. Then register each durable stream by stable identifier before
+calling `start()`:
 
 ```js
 await set.detach()
 
 const replacement = new MultiplexedSocketductTransportSet(sameSetOptions)
 const recovered = replacement.recoverConnection({
-  routeClass: durableRecord.routeClass, // exact sets use gatewayId instead
-  host: "api.internal",
-  port: 443,
-  identifier: "build_stream_01",
-  sessionName: "build"
+  identifier: "build_stream_01"
 })
 await replacement.start()
 ```
 
-`recoverConnection()` implies durable recovery and rejects a missing,
-ambiguous, invalid, or unknown original selector, an explicit `recover` option,
-or registration after `start()` has begun. It bypasses selection only to reach
-that configured member; it never migrates or replays the stream on a sibling.
+`recoverConnection()` implies durable recovery. Identifier-only lookup restores
+the target, name, receive-ACK mode, and original member from private spool
+metadata. It fails with `SOCKETDUCT_RECOVERY_NOT_FOUND` when no configured
+namespace owns the identifier and `SOCKETDUCT_RECOVERY_AMBIGUOUS` when more than
+one does. It also rejects corrupt state, an explicit `recover` option, or
+registration after `start()` begins. The legacy exact-selector form remains
+valid. Recovery never migrates or replays the stream on a sibling.
 Ordinary `createConnection()` and
 `createTlsConnection()` reject `recover: true`, `gatewayId`, and `routeClass`,
 so new opens cannot force a path. `detach()` coalesces with concurrent shutdown calls,
@@ -269,6 +266,14 @@ buffer is discarded, but shared spool capacity remains reserved until the
 corresponding durable truncate or remove succeeds. Failed cleanup keeps that
 capacity occupied and fails the affected member visibly.
 
+For reverse members, `manualReceiveAck: true` changes inbound ownership from the
+default automatic ACK to explicit `await socket.acknowledgeReceive(bytes)` after
+the caller's parser or journal commit. `writeDurable(bytes)` atomically admits a
+complete serialized operation and resolves only after its full raw payload and
+send sequence are committed. Ordinary `write()` and default receive behavior
+are unchanged. See [Native reverse gateway](reverse-gateway.md#failure-and-replay-boundary)
+for limits, retry, detach, duplicate-call, and error semantics.
+
 `status()` returns only safe aggregate counts/bytes, `pendingOpens`, its maximum,
 and an ordered member list:
 gateway ID or route class, lifecycle state, assignments, physical connects/reconnects, virtual
@@ -320,7 +325,7 @@ socket.on("data", (chunk) => process.stdout.write(chunk))
 `SocketductSocket` should extend `Duplex` and expose the common socket fields/methods that libraries usually probe:
 
 - events: `connect`, `ready`, `data`, `end`, `close`, `error`, `timeout`, `drain`
-- methods: `connect`, `write`, `end`, `destroy`, `pause`, `resume`, `setTimeout`, `setNoDelay`, `setKeepAlive`, `address`, `ref`, `unref`
+- methods: `connect`, `write`, `writeDurable`, `acknowledgeReceive`, `end`, `destroy`, `pause`, `resume`, `setTimeout`, `setNoDelay`, `setKeepAlive`, `address`, `ref`, `unref`
 - properties: `connecting`, `destroyed`, `pending`, `remoteAddress`, `remotePort`, `localAddress`, `localPort`, `bytesRead`, `bytesWritten`
 
 The constructor should configure the socket without opening the relay connection. The public `.connect()` method starts relay connection/session create or resume and returns `this`, matching Node's chaining style. `connectSocketduct(options)` is the convenience wrapper that constructs `new SocketductSocket(options)`, schedules `.connect()`, and returns the socket immediately.

package/package.json

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

package/src/client/deferred-virtual-socket.js

@@ -47,6 +47,12 @@ class DeferredSocketOwner {
   /** @type {boolean} */
   #cancelled = false
 
+  /** @type {number} */
+  #deliveredBytes = 0
+
+  /** @type {number} */
+  #acknowledgedBytes = 0
+
   /** @param {DeferredVirtualSocketOptions} options - Set-owned deferred socket policy. */
   constructor(options) {
     this.#budget = options.budget
@@ -149,6 +155,19 @@ class DeferredSocketOwner {
     this.#inner.write(data, callback)
   }
 
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {Buffer} data - Complete durable operation.
+   * @param {(error?: Error | null) => void} callback - Completion.
+   */
+  _writeDurableStream(_streamId, data, callback) {
+    if (this.#inner === undefined) {
+      callback(new SocketductStreamError("Durable write requires an assigned Socketduct member", "SOCKETDUCT_DURABLE_WRITE_UNAVAILABLE"))
+      return
+    }
+    this.#inner.writeDurable(data).then(() => callback(), callback)
+  }
+
   /**
    * @param {number} _streamId - Facade stream ID.
    * @param {(error?: Error | null) => void} callback - Completion.
@@ -191,6 +210,28 @@ class DeferredSocketOwner {
     if (this.#inner !== undefined) this.#inner.resume()
   }
 
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {number} bytes - Bytes exposed by the facade.
+   */
+  _deliverReadable(_streamId, bytes) {
+    this.#deliveredBytes += bytes
+  }
+
+  /**
+   * @param {number} _streamId - Facade stream ID.
+   * @param {number} bytes - Newly durable application bytes.
+   */
+  _acknowledgeReadable(_streamId, bytes) {
+    if (this.#inner === undefined) return Promise.reject(new SocketductStreamError("Manual receive acknowledgement requires an assigned Socketduct member", "SOCKETDUCT_MANUAL_ACK_UNAVAILABLE"))
+    if (this.#acknowledgedBytes + bytes > this.#deliveredBytes) return Promise.reject(new SocketductStreamError("Receive acknowledgement exceeds bytes delivered to the application", "SOCKETDUCT_INVALID_RECEIVE_ACK"))
+    this.#acknowledgedBytes += bytes
+    return this.#inner.acknowledgeReceive(bytes).catch((error) => {
+      this.#acknowledgedBytes -= bytes
+      throw error
+    })
+  }
+
   /** References the assigned member or the whole set while pending. */
   ref() {
     if (this.#inner === undefined) this.#ref()
@@ -216,7 +257,7 @@ export class DeferredVirtualSocket extends VirtualSocket {
   #routeClass
 
   /**
-   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Target/socket options.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number, manualReceiveAck?: boolean}} socketOptions - Target/socket options.
    * @param {DeferredVirtualSocketOptions} deferredOptions - Set-owned wait policy.
    */
   constructor(socketOptions, deferredOptions) {

package/src/client/multiplexed-connection.js

@@ -51,6 +51,7 @@ const STABLE_IDENTIFIER = /^[A-Za-z0-9_-]{8,128}$/
  * @property {string} [sessionName] - Human-readable stream name.
  * @property {string} [identifier] - Stable resumable identifier.
  * @property {boolean} [recover] - Recover this stream from its existing durable v3 spool.
+ * @property {boolean} [manualReceiveAck] - Reverse-client-only application-controlled durable receive ACK.
  * @property {boolean} [allowHalfOpen] - Duplex half-close behavior.
  * @property {number} [readableHighWaterMark] - Readable buffer threshold.
  * @property {number} [writableHighWaterMark] - Writable buffer threshold.
@@ -274,6 +275,21 @@ export class MultiplexedSocketductConnection extends EventEmitter {
     return this.#createConnection(options, callback, false)
   }
 
+  /**
+   * Reads and validates one durable descriptor without allocating a socket.
+   * @param {string} identifier - Stable stream identifier.
+   * @returns {{identifier: string, target: {host: string, port: number}, sessionName: string, manualReceiveAck: false} | undefined} Recovery descriptor.
+   */
+  _inspectRecoveredConnection(identifier) {
+    if (typeof identifier !== "string" || !STABLE_IDENTIFIER.test(identifier)) throw new TypeError("Virtual stream identifier must be 8-128 URL-safe opaque characters")
+    const value = this.#spool.findRecoveryStateSync(identifier, "edge-v3")
+    if (value === undefined) return undefined
+    const rawTarget = /** @type {{target?: unknown}} */ (value).target
+    const target = normalizeTarget(/** @type {VirtualConnectionOptions} */ ({target: rawTarget}))
+    const state = validateRecoveryState(value, {connectionId: this.#connectionId, identifier, target})
+    return {identifier, target, sessionName: state.name, manualReceiveAck: false}
+  }
+
   /**
    * @param {VirtualConnectionOptions} options - Target/socket options.
    * @param {((error: Error | null, socket: VirtualSocket) => void) | undefined} callback - Node-style optional callback.
@@ -282,6 +298,7 @@ export class MultiplexedSocketductConnection extends EventEmitter {
    */
   #createConnection(options, callback, connectOnReady) {
     if (this.#closing) throw new Error("Multiplexed Socketduct connection is closed")
+    if (options.manualReceiveAck !== undefined) throw new TypeError("manualReceiveAck is supported only by reverse gateway connections")
     if (this.#streams.size >= (this.#options.maxStreams ?? DEFAULT_MAX_STREAMS)) throw new Error("Maximum virtual stream count exceeded")
     const target = normalizeTarget(options)
     const identifier = options.identifier ?? randomBytes(24).toString("base64url")

package/src/client/multiplexed-transport-set.js

@@ -56,6 +56,7 @@ const GATEWAY_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$/
  * @property {() => Promise<void>} connect - Warm the member.
  * @property {(options: Record<string, unknown>, callback?: (error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) => import('./virtual-socket.js').VirtualSocket} createConnection - Open a virtual stream.
  * @property {(options: Record<string, unknown>, callback?: (error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) => import('./virtual-socket.js').VirtualSocket} registerRecoveredConnection - Cold-register durable recovery.
+ * @property {(identifier: string) => {identifier: string, target: {host: string, port: number}, sessionName: string, manualReceiveAck: boolean} | undefined} [_inspectRecoveredConnection] - Read-only stable-identifier recovery lookup.
  * @property {() => MemberConnectionStatus} status - Privacy-safe status.
  * @property {() => Promise<void>} close - Close the member.
  * @property {() => Promise<void>} detach - Preserve durable streams for process-replacement recovery.
@@ -112,6 +113,19 @@ export class SocketductTransportSetTerminalError extends AggregateError {
   }
 }
 
+/** Stable-identifier recovery found no unique durable owner. */
+export class SocketductRecoveryLookupError extends Error {
+  /**
+   * @param {string} message - Privacy-safe detail.
+   * @param {'SOCKETDUCT_RECOVERY_NOT_FOUND' | 'SOCKETDUCT_RECOVERY_AMBIGUOUS'} code - Stable classification.
+   */
+  constructor(message, code) {
+    super(message)
+    this.name = "SocketductRecoveryLookupError"
+    this.code = code
+  }
+}
+
 /** Shared retained-byte reservations across every configured member. */
 class AggregateTransportBudget {
   #memoryBytes = 0
@@ -343,7 +357,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
   /**
    * Returns an app-facing socket while the set owns readiness and assignment.
    * @param {import('./multiplexed-connection.js').VirtualConnectionOptions} options - Validated member open options.
-   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Normal socket metadata.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number, manualReceiveAck?: boolean}} socketOptions - Normal socket metadata.
    * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
    * @returns {GatewayVirtualSocket} Deferred socket.
    */
@@ -381,7 +395,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
 
   /**
    * Creates a socket that asynchronously reports the already-terminal startup failure.
-   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} socketOptions - Normal socket metadata.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number, manualReceiveAck?: boolean}} socketOptions - Normal socket metadata.
    * @param {Error} error - Terminal startup failure.
    * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
    * @returns {GatewayVirtualSocket} Failed socket facade.
@@ -400,7 +414,7 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
 
   /**
    * Registers a durable stream on its one original member before any member starts.
-   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & ({gatewayId: string, routeClass?: never} | {routeClass: string, gatewayId?: never})} options - Original gateway or route-class recovery identity.
+   * @param {import('./multiplexed-connection.js').VirtualConnectionOptions & ({gatewayId: string, routeClass?: never} | {routeClass: string, gatewayId?: never} | {gatewayId?: never, routeClass?: never})} options - Stable identifier with an optional legacy exact selector.
    * @param {(error: Error | null, socket: GatewayVirtualSocket) => void} [callback] - Existing callback convention.
    * @returns {GatewayVirtualSocket} Original member-owned virtual socket with stable gateway metadata.
    */
@@ -410,16 +424,36 @@ export class MultiplexedSocketductTransportSet extends EventEmitter {
     if (typeof options !== "object" || options === null) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
     const hasGatewayId = Object.hasOwn(options, "gatewayId")
     const hasRouteClass = Object.hasOwn(options, "routeClass")
-    if (hasGatewayId === hasRouteClass) throw new TypeError("recoverConnection requires exactly one configured gatewayId or routeClass")
+    if (hasGatewayId && hasRouteClass) throw new TypeError("recoverConnection accepts at most one configured gatewayId or routeClass")
     if (hasGatewayId && (typeof options.gatewayId !== "string" || !GATEWAY_ID.test(options.gatewayId))) throw new TypeError("recoverConnection requires a valid configured gatewayId")
     if (hasRouteClass && (typeof options.routeClass !== "string" || !ROUTE_CLASS.test(options.routeClass))) throw new TypeError("recoverConnection requires a valid configured routeClass")
     if (Object.hasOwn(options, "recover")) throw new TypeError("recoverConnection owns the recover option")
-    const selector = hasGatewayId ? options.gatewayId : options.routeClass
-    const member = this.#members.find((candidate) => hasGatewayId ? candidate.gatewayId === selector : candidate.routeClass === selector)
-    if (member === undefined) throw new Error(`Unknown ${hasGatewayId ? "gatewayId" : "routeClass"}: ${selector}`)
+    if (typeof options.identifier !== "string" || !STABLE_IDENTIFIER.test(options.identifier)) throw new TypeError("recoverConnection requires a stable 8-128 character identifier")
+    let member
+    /** @type {{identifier: string, target: {host: string, port: number}, sessionName: string, manualReceiveAck: boolean} | undefined} */
+    let descriptor
+    if (!hasGatewayId && !hasRouteClass) {
+      const matches = this.#members.flatMap((candidate) => {
+        const recovered = candidate.connection._inspectRecoveredConnection?.(/** @type {string} */ (options.identifier))
+        return recovered === undefined ? [] : [{member: candidate, descriptor: recovered}]
+      })
+      if (matches.length === 0) throw new SocketductRecoveryLookupError("No durable Socketduct stream matches the stable identifier", "SOCKETDUCT_RECOVERY_NOT_FOUND")
+      if (matches.length > 1) throw new SocketductRecoveryLookupError("Durable Socketduct stream identifier is ambiguous across configured members", "SOCKETDUCT_RECOVERY_AMBIGUOUS")
+      member = /** @type {{member: TransportMember, descriptor: NonNullable<typeof descriptor>}} */ (matches[0]).member
+      descriptor = /** @type {{member: TransportMember, descriptor: NonNullable<typeof descriptor>}} */ (matches[0]).descriptor
+    } else {
+      const selector = hasGatewayId ? options.gatewayId : options.routeClass
+      member = this.#members.find((candidate) => hasGatewayId ? candidate.gatewayId === selector : candidate.routeClass === selector)
+      if (member === undefined) throw new Error(`Unknown ${hasGatewayId ? "gatewayId" : "routeClass"}: ${selector}`)
+    }
     const virtualOptions = {...options}
     delete /** @type {{gatewayId?: string}} */ (virtualOptions).gatewayId
     delete /** @type {{routeClass?: string}} */ (virtualOptions).routeClass
+    if (descriptor !== undefined) {
+      if (virtualOptions.target === undefined && virtualOptions.host === undefined && virtualOptions.port === undefined) virtualOptions.target = descriptor.target
+      if (virtualOptions.sessionName === undefined) virtualOptions.sessionName = descriptor.sessionName
+      if (virtualOptions.manualReceiveAck === undefined && descriptor.manualReceiveAck) virtualOptions.manualReceiveAck = true
+    }
     const allocation = memberAllocation(member)
     /** @type {((error: Error | null, socket: import('./virtual-socket.js').VirtualSocket) => void) | undefined} */
     const memberCallback = callback === undefined ? undefined : (error, socket) => callback(error, exposeAllocation(socket, allocation))
@@ -822,7 +856,8 @@ function normalizeVirtualSocketOptions(options) {
     port: target.port,
     ...(options.allowHalfOpen === undefined ? {} : {allowHalfOpen: options.allowHalfOpen}),
     ...(options.readableHighWaterMark === undefined ? {} : {readableHighWaterMark: options.readableHighWaterMark}),
-    ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark})
+    ...(options.writableHighWaterMark === undefined ? {} : {writableHighWaterMark: options.writableHighWaterMark}),
+    ...(options.manualReceiveAck === undefined ? {} : {manualReceiveAck: options.manualReceiveAck})
   }
 }
 

package/src/client/multiplexed.js

@@ -1,3 +1,3 @@
 export {createMultiplexedSocketductConnection, MultiplexedSocketductConnection} from "./multiplexed-connection.js"
-export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./multiplexed-transport-set.js"
+export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductRecoveryLookupError, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./multiplexed-transport-set.js"
 export {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "./virtual-socket.js"