socketduct 0.1.19 → 0.1.21

package/.env.example

@@ -19,16 +19,23 @@ SOCKETDUCT_RESUME_WINDOW_MS=30000
 # Emit secret-free JSON runtime counters at this interval. Set 0 to disable.
 SOCKETDUCT_STATUS_INTERVAL_MS=30000
 
-# Optional bounded persistent JSONL logs. Bind mount this directory from host
-# storage in Docker. Files are isolated by role/PID; defaults are 10 MiB and 5
-# retained files including the active file. Existing stdout/stderr is preserved.
+# Optional durable compressed JSONL logs. Bind mount this directory from host
+# storage in Docker. Standard checksummed zstd frames and their private index
+# are written by an isolated worker. Existing stdout/stderr is preserved.
 # Host directory mounted by the checked-in production Compose files. Create it
 # for uid/gid 1000 before deployment. Logging stays disabled unless the
 # container-side SOCKETDUCT_LOG_DIRECTORY is also set.
 # SOCKETDUCT_LOG_HOST_DIRECTORY=/srv/socketduct/logs
 # SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
-# SOCKETDUCT_LOG_MAX_FILE_BYTES=10485760
-# SOCKETDUCT_LOG_MAX_FILES=5
+# SOCKETDUCT_LOG_FRAME_MAX_BYTES=1048576
+# SOCKETDUCT_LOG_FLUSH_INTERVAL_MS=1000
+# SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS=250
+# SOCKETDUCT_LOG_SEGMENT_MAX_BYTES=134217728
+# SOCKETDUCT_LOG_RETENTION_DAYS=30
+# SOCKETDUCT_LOG_RETENTION_MAX_BYTES=4294967296
+# SOCKETDUCT_LOG_QUEUE_MAX_BYTES=67108864
+# SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES=8388608
+# SOCKETDUCT_LOG_COMPRESSION_LEVEL=19
 
 # Per-session hard byte limit for target-to-client data buffered while the
 # edge tunnel is detached. When the limit is exceeded the relay terminates
@@ -113,6 +120,11 @@ SOCKETDUCT_TARGET_ALLOWLIST=docker-socket-shim:2375
 # Server3 hub: change SOCKETDUCT_MODE to reverse-hub, keep the TLS server pair
 # above, and bind every stable gateway ID to its credential username.
 # SOCKETDUCT_REVERSE_GATEWAY_BINDINGS=o2:home-o2,zyxel:home-zyxel,starlink:home-starlink
+# Required when a reverse hub enables SOCKETDUCT_LOG_DIRECTORY. Generate 32-64
+# random bytes, encode them as unpadded base64url, keep the key hub-only, and
+# rotate it with the public URL-safe epoch label at least every 30 days.
+# SOCKETDUCT_CONNECTION_FINGERPRINT_KEY=<unpadded-base64url-secret>
+# SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH=2026-09
 # Authorize exact client username, gateway ID, and home-local target tuples.
 # SOCKETDUCT_REVERSE_ROUTES=tensorbuzz:o2:docker-server:2375,tensorbuzz:zyxel:docker-server:2375,tensorbuzz:starlink:docker-server:2375
 # Or bind one client physical connection to a route class and resolve each

package/README.md

@@ -35,8 +35,8 @@ Normal TCP sockets cannot magically resume after the underlying internet path di
   sockets, and deterministic per-socket round-robin across ready members
 - native reverse-gateway v3 lets authenticated private home members register
   outbound with a Server3 hub, so CGNAT paths need no inbound forwarding
-- optional bounded JSONL lifecycle logs can be written to per-process files in
-  a Docker bind-mounted directory without replacing existing stdout/stderr
+- optional bounded diagnostic JSONL is stored as checksummed standard zstd
+  frames with an owned tail/search CLI, without replacing stdout/stderr
 
 ## MVP goals
 
@@ -113,7 +113,7 @@ hub address because `gatewayId` selects the outbound member. Docker remains
 - [Docker topology](docs/docker-topology.md)
 - [Node-compatible socket API design](docs/socket-api.md)
 - [Native reverse gateway](docs/reverse-gateway.md)
-- [Persistent structured logging](docs/logging.md)
+- [Durable compressed diagnostic logs](docs/logging.md)
 - [Initial implementation plan](docs/plans/initial-implementation.md)
 - [Socket + Docker integration plan](docs/plans/socket-docker-integration.md)
 

package/changelog.d/20260925170000-disconnect-attribution-compressed-logs.md

@@ -0,0 +1 @@
+Socketduct now preserves reverse disconnect causes across terminal errors and writes bounded, recovery-safe indexed zstd diagnostics with incremental owned tail/search behavior.

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/docs/docker.md

@@ -162,14 +162,15 @@ sudo install -d -o 1000 -g 1000 -m 0700 /srv/socketduct/logs
 ```text
 SOCKETDUCT_LOG_HOST_DIRECTORY=/srv/socketduct/logs
 SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
-SOCKETDUCT_LOG_MAX_FILE_BYTES=10485760
-SOCKETDUCT_LOG_MAX_FILES=5
+SOCKETDUCT_LOG_SEGMENT_MAX_BYTES=134217728
+SOCKETDUCT_LOG_RETENTION_DAYS=30
+SOCKETDUCT_LOG_RETENTION_MAX_BYTES=4294967296
 ```
 
 The production relay and reverse-gateway Compose files mount the host directory
 at `/var/log/socketduct`. Existing container stdout/stderr remains enabled. See
-[Persistent structured logging](logging.md) for file names, rotation, embedded
-client configuration, and the redaction contract.
+[durable compressed diagnostic logs](logging.md) for the indexed frame layout,
+owned tail/search CLI, rotation, embedded configuration, and privacy contract.
 
 Expected startup log (formatted here for readability; the actual line is JSON):
 

package/docs/logging.md

@@ -1,185 +1,157 @@
-# Persistent structured logging
+# Durable compressed diagnostic logs
 
-Socketduct can write lifecycle diagnostics as newline-delimited JSON (JSONL) to
-a directory mounted from persistent host storage. File logging is opt-in.
-Existing startup/status output on stdout and errors on stderr remain unchanged
-when file logging is enabled.
+Socketduct’s managed runtime can write sanitized lifecycle diagnostics as
+newline-delimited JSON records inside standard Zstandard frames. Logging remains
+opt-in: set `SOCKETDUCT_LOG_DIRECTORY` for a `relay`, `reverse-hub`,
+`reverse-gateway`, or summary process. Existing stdout/stderr output is unchanged.
 
-## Standalone runtime configuration
+The managed sink never falls back to plaintext. The older
+`createJsonlFileLogger()` API remains available only for embedded callers that
+explicitly select its legacy plaintext files; managed runtimes use
+`createCompressedJsonlFileLogger()`.
 
-Set `SOCKETDUCT_LOG_DIRECTORY` for a `relay`, `reverse-hub`, or
-`reverse-gateway` process:
+## Configuration
 
 ```sh
 SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
-SOCKETDUCT_LOG_MAX_FILE_BYTES=10485760
-SOCKETDUCT_LOG_MAX_FILES=5
+SOCKETDUCT_LOG_FRAME_MAX_BYTES=1048576
+SOCKETDUCT_LOG_FLUSH_INTERVAL_MS=1000
+SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS=250
+SOCKETDUCT_LOG_SEGMENT_MAX_BYTES=134217728
+SOCKETDUCT_LOG_RETENTION_DAYS=30
+SOCKETDUCT_LOG_RETENTION_MAX_BYTES=4294967296
+SOCKETDUCT_LOG_QUEUE_MAX_BYTES=67108864
+SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES=8388608
+SOCKETDUCT_LOG_COMPRESSION_LEVEL=19
 ```
 
-`SOCKETDUCT_LOG_MAX_FILE_BYTES` defaults to 10 MiB and must be at least 1024.
-`SOCKETDUCT_LOG_MAX_FILES` defaults to 5, includes the active file, and must be
-between 1 and 100. The size/count settings are ignored unless a non-empty log
-directory enables the sink.
-
-Each process writes its own `<role>-<pid>.jsonl` file, with older files renamed
-to `.1`, `.2`, and so on. A writer never rotates another live process's active
-file, which avoids cross-process rename races. Each file in the current
-process/role family is bounded by the configured byte limit and the family
-retains at most the configured file count. A reused PID continues the same
-bounded filename family.
-
-On its first write, a logger also caps files left by definitely exited
-same-role process instances to the configured file count in total, retaining
-the newest files. Repeated signal-0 PID probes must report `ESRCH`, and the file
-must remain unchanged, before it can be deleted. A live/reused PID, permission
-failure, unsupported probe, changed file, or other indeterminate result
-preserves every file in that family. Files are created with mode `0600`; a newly
-created log directory uses mode `0700`.
-
-For Docker, bind mount a persistent host directory and point Socketduct at the
-container path:
-
-```yaml
-services:
-  socketduct:
-    environment:
-      SOCKETDUCT_LOG_DIRECTORY: /var/log/socketduct
-      SOCKETDUCT_LOG_MAX_FILE_BYTES: "10485760"
-      SOCKETDUCT_LOG_MAX_FILES: "5"
-    volumes:
-      - /srv/socketduct/logs:/var/log/socketduct
-```
+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.
+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`
+plaintext settings are rejected instead of being silently applied to the new
+format.
 
-Create `/srv/socketduct/logs` with mode `0700` and ownership that permits the
-container user to write it; for uid/gid 1000, use
-`sudo install -d -o 1000 -g 1000 -m 0700 /srv/socketduct/logs`.
-A permission, disk, or rotation error does not change tunnel,
-session, target, or reconnect behavior. Socketduct reports only
-`Socketduct logger failure (LOGGER_IO_ERROR)` to stderr, at most once per
-logger, without including the path or underlying error text.
-
-## Interrupted writes and retained evidence
-
-Before appending, the file sink checks the last byte of a nonempty active file.
-This bounded check also runs for a fresh logger or restarted process reusing
-the same filename; it does not scan or parse historical records. A failed
-append may have written a prefix even when the filesystem reports an error.
-
-If the active file does not end in a newline, Socketduct moves the entire file
-byte-for-byte into the existing numbered retention family and writes subsequent
-events to a clean active file. The retained segment may still contain an
-incomplete final record: it is incident evidence, not repaired JSONL. Normal
-bounded retention eventually ages it out, so preserve incident evidence outside
-the managed family before rollout or forensic work. New complete records must
-parse independently; ignoring malformed historical lines is not proof of recovery.
-
-If tail inspection, rotation, clean-file creation, or mode verification fails,
-that logging call writes no new record. Later ordinary calls recheck the
-filesystem; there is no background retry loop or replay of missed diagnostics.
-If an append itself fails, it may leave another incomplete prefix that the next
-call must separate. Logging failures still do not interrupt tunnel traffic.
-
-With `maxFiles: 1`, there is no retained slot: an incomplete active file is left
-untouched and file logging pauses. An incomplete active file already larger
-than a newly lowered size limit also pauses logging **before startup pruning**;
-it is not deleted to satisfy that limit. These pre-existing bytes can remain
-outside the newly configured bound, but Socketduct will not grow them. An
-operator must preserve the evidence separately and provide a clean path before
-logging can continue. Socketduct never truncates or rewrites damaged records.
-Already newline-terminated malformed historical records are not repaired.
-
-The sink requires a regular active file with mode `0600` and a directory with
-mode `0700`, including on reused paths. It checks the newly created file's
-actual mode before writing and does not follow an active-file symlink. Fix
-ownership/modes on an operator-preserved path rather than making logs public.
-
-See [the private rollout runbook](runbooks/jsonl-integrity-rollout.md) for the
-isolated fault commands and evidence-preserving Apoc-only rollout gates.
-
-The checked-in production relay and reverse-gateway Compose files already mount
-`${SOCKETDUCT_LOG_HOST_DIRECTORY:-./logs}` at `/var/log/socketduct`. Enable the
-sink in `.env` after creating the host directory for the container's uid/gid
-1000:
+A reverse hub that enables managed logging must also configure a hub-only
+correlation key:
 
 ```sh
-SOCKETDUCT_LOG_HOST_DIRECTORY=/srv/socketduct/logs
-SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY='<unpadded-base64url-at-least-32-bytes>'
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH='2026-09'
 ```
 
-`SOCKETDUCT_STATUS_INTERVAL_MS` controls both console and file-backed periodic
-status events. Its default remains 30000 milliseconds; `0` disables periodic
-status only, not lifecycle logging.
+Generate the key from random bytes, keep it out of gateways and clients, rotate
+it at least every 30 days and on suspected exposure, and remove the previous
+key after at most 24 hours of rollout overlap. The epoch is a public 1–32
+character URL-safe label. Socketduct logs only the role-separated first 128 bits
+of an HMAC-SHA-256 fingerprint; it never emits the key or raw connection ID.
 
-## Embedded client configuration
+## Storage and durability
 
-Create one file logger per process/role and pass it to the client, agent, or
-transport set through its `logger` option:
+The directory must be a real `0700` directory. Socketduct creates exclusive
+`0600` files without following symlinks:
 
-```js
-import {createJsonlFileLogger} from "socketduct"
-import {MultiplexedSocketductTransportSet} from "socketduct/multiplexed"
+```text
+<role>-<writerEpoch>-<segmentUuid>.jsonl.zst
+<role>-<writerEpoch>-<segmentUuid>.jsonl.zst.idx
+<role>-<writerEpoch>-<segmentUuid>.jsonl.zst.sealed
+```
 
-const logger = createJsonlFileLogger({
-  directory: "/var/log/socketduct",
-  role: "tensorbuzz-client",
-  maxFileBytes: 10 * 1024 * 1024,
-  maxFiles: 5
-})
+Every `.jsonl.zst` segment is a concatenation of independently decodable,
+checksummed, standard zstd frames at level 19. Each frame contains complete
+newline-terminated records only. Compression and filesystem sync run in a
+dedicated worker thread, off the protocol event loop.
+
+The versioned big-endian sidecar index contains structural identities, sequence
+ranges, offsets, lengths, timestamps, frame SHA-256, and CRC32C checks. It does
+not contain gateways, routes, incidents, reasons, connection IDs, or search
+digests. A batch becomes durable only after Socketduct writes and `fdatasync`s
+the data frame, appends and `fdatasync`s its index entry, then acknowledges the
+exact deterministic batch identity to the producer.
+
+On worker restart, Socketduct validates every retained segment, accepts a
+retention-deleted sequence prefix, and still rejects gaps or duplicates inside
+the retained range. It rebuilds one fully decodable data-synced orphan entry,
+truncates only a torn final data or index tail, and replays only a batch not
+proven durable by the high-water mark plus the single latest batch identity;
+worker memory and acknowledgement size do not grow with history. Interior
+corruption is preserved and marked quarantined; readers report incomplete
+evidence. Retention deletes only oldest sealed, non-quarantined segments under
+an exclusive process/thread-instance lock. A crashed owner is reclaimed using
+PID/TID plus kernel start identities, while a live or unprovable owner remains fail-closed.
+Active and quarantined bytes count toward the quota and are never deleted to
+hide a failure.
+
+`log()` is nonblocking and reports `accepted`, `coalesced`, or `dropped`.
+`flush()` is a caller-time sequence barrier: it resolves after every record
+accepted through that call is data-and-index durable, without waiting for later
+producers. Idempotent async `close()` stops acceptance, drains all records and
+bounded sink lifecycle records, seals, syncs, and terminates the worker. `status()` exposes writer and
+durable high-water marks, allocated bytes, health, restart count, and exact drop
+counters. Orderly SIGINT/SIGTERM closes the network runtime first, records the
+final process lifecycle event, then awaits logger flush and close before exit.
+The startup record includes the effective numeric logger settings but never the
+configured directory or key material.
+
+## Owned reader and CLI
+
+Do not use `tail -f` on compressed bytes. Socketduct reads each indexed frame
+independently and verifies the full integrity chain:
 
-const transports = new MultiplexedSocketductTransportSet({
-  connectionId: "runner_01_stable_identity",
-  spoolDirectory: "/tmp/socketduct-v3-set",
-  gateways,
-  logger
-})
+```sh
+socketduct logs tail --directory /var/log/socketduct
+socketduct logs tail --directory /var/log/socketduct --follow
+socketduct logs search --directory /var/log/socketduct --incident '<22-char-id>'
+socketduct logs search --directory /var/log/socketduct --event reverse_hub.physical_detached
 ```
 
-The same `logger` option is supported by `MultiplexedSocketductConnection`,
-`ReverseGatewayConnection`, `OutboundReverseGateway`, `connectSocketduct`,
-`createSocketductConnectionFactory`, `SocketductHttpAgent`, and
-`SocketductHttpsAgent`. A transport set owns logger propagation to its members;
-do not put `logger` inside `memberOptions`.
-
-For an existing logging system, use the exported line-writer adapter:
+Search filters include `--event`, `--incident`, `--gateway`, `--route-class`,
+`--client-generation`, `--gateway-generation`, `--reason`, `--since`, and
+`--until`. Records from all writers are merged deterministically by timestamp,
+raw writer epoch, and numeric event sequence; that ordering does not imply
+cross-process causality. Search exits `0` for one or more matches, `1` for no
+matches in complete evidence, and `2` for invalid arguments, I/O failure, or
+any selected corrupt/quarantined/incomplete segment. Tail returns `2` on the
+same evidence failures. Closed segments also remain compatible with ordinary
+`zstdcat` and `zstdgrep`. Follow mode advances sidecar-index cursors and decodes
+only newly committed frames. Cursor state is limited to currently retained
+segments and is pruned as retention removes closed segments, so rotation does
+not cause duplicate output or repeated historical decompression.
+
+## Privacy boundary
+
+Records retain the existing 1,024-byte closed event/field allowlist. Disconnect
+events may include a random incident ID, first local cause, origin and physical
+role, explicitly named client/gateway generations, fan-out/resume/terminal
+counts, safe gateway or route identity, safe socket code, and the hub-only keyed
+fingerprint. Public terminal codes classify the outcome; they do not overwrite
+the physical cause.
+
+Socketduct never persists payload bytes, Docker requests or targets, tokens,
+passwords, certificates or keys, raw connection IDs, HMAC keys, unkeyed identity
+digests, peer-controlled reserved fields, spool paths/data, or arbitrary caller
+objects. Logger health reports use fixed secret-free classifications.
+
+## Embedded use
 
 ```js
-import {createStructuredLogger} from "socketduct"
+import {createCompressedJsonlFileLogger} from "socketduct"
 
-const logger = createStructuredLogger({
-  role: "tensorbuzz-client",
-  writeLine(line) {
-    destination.append(line)
-  }
+const logger = createCompressedJsonlFileLogger({
+  directory: "/var/log/socketduct",
+  role: "tensorbuzz-client"
 })
+
+transportOptions.logger = logger
+// At shutdown, after stopping producers:
+await logger.flush()
+await logger.close()
 ```
 
-Alternatively, pass an object with `log(event, fields)` directly. Socketduct
-calls it only with a known event and already-sanitized fields. A direct custom
-logger is responsible for adding its own timestamp/process/role envelope and
-for preserving one-object-per-line framing. Synchronous throws and rejected
-promises from custom loggers/writers are isolated from connection behavior.
-
-## Event and data contract
-
-The built-in logger emits one JSON object per line, capped at 1024 bytes. Every
-entry contains an ISO-8601 `timestamp`, an allowlisted `event`, numeric
-`processId`, and validated `role`. Depending on the component, events cover:
-
-- process startup and periodic status counters
-- physical transport connect, disconnect, retry scheduling, recovery, and
-  terminal failure
-- transport-set readiness, member state/generation replacement, and terminal
-  loss
-- reverse-gateway target open success, open failure, and close
-- virtual-stream opening, opened, closed, and error transitions
-
-Only finite allowlisted booleans, non-negative integer counters, validated
-gateway IDs, states, and error classifications can be included. Unknown events
-are dropped. Unknown error codes become `UNKNOWN`. Errors supplied through
-`errorDiagnostics()` retain their name, message, and stack so terminal
-transport and virtual-stream failures are actionable.
-
-The diagnostic path never serializes protocol payloads or arbitrary caller
-fields. It serializes error messages and stack traces produced by
-`errorDiagnostics()` after redacting bearer credentials, URL userinfo, and
-password/token/authorization values.
+The `logger` option remains supported by Socketduct client, agent, transport-set,
+and reverse-gateway APIs. A direct custom logger remains responsible for its own
+durability. The legacy plaintext factory does not gain compressed recovery or
+CLI guarantees and does not rewrite existing `.jsonl` 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
@@ -181,6 +199,28 @@ payloads terminate the physical connection. TLS certificate verification is
 mandatory for every reverse client and gateway transport. The complete role
 contract is in [Native reverse gateway](reverse-gateway.md).
 
+### Reverse disconnect attribution
+
+Authenticated reverse GOAWAY and terminal RESET controls may carry the hub’s
+closed attribution object: a 22-character random `disconnectIncidentId`, fixed
+`disconnectReason`, `incidentOrigin`, `physicalRole`, applicable
+`clientConnectionGeneration` / `gatewayConnectionGeneration`, and nonnegative
+`fanOutCount`, `resumeSuccessCount`, and `terminalStreamCount`. A valid hub
+incident takes precedence over a locally observed close. Endpoints preserve it
+on public typed errors. The `code` remains a terminal classification and is not
+interpreted as the transport cause.
+
+The hub creates attribution before every retained or terminal fan-out. This
+includes protocol/output-limit termination, replacement, peer GOAWAY, orderly
+hub shutdown, direct transport loss, and resume expiry. A syntactically safe
+peer GOAWAY `code` may classify resulting terminal RESETs, but peer attribution
+fields are never trusted and cannot replace the hub-observed physical cause.
+
+These names are hub-reserved. Attribution, fingerprint, and epoch fields in a
+gateway-forwarded RESET are stripped before forwarding; malformed or unknown
+values never become trusted telemetry. No control carries raw connection IDs,
+HMAC keys, targets, credentials, certificates, or payload data.
+
 ## Legacy protocol version 2
 
 V2 starts every connection with the length-prefixed JSON envelope
@@ -516,10 +556,11 @@ it, because every frame declares its own encoding.
 
 ### Runtime support
 
-zstd is provided by `node:zlib`, which only exposes it from Node 22.15 onward,
-while `engines` accepts Node >=22.0. Support is therefore feature-detected at
-runtime: a peer whose Node lacks zstd advertises no codec and the tunnel runs
-raw. No runtime dependency is added.
+zstd is provided by Node 24's `node:zlib`; the package requires Node 24 or
+newer. Stream-data support is still negotiated, so an explicitly disabled
+codec runs raw. Durable diagnostic storage separately requires checksummed
+standard zstd frames and never falls back to plaintext. No runtime dependency
+is added.
 
 ## Acknowledgements
 

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
@@ -198,6 +238,9 @@ SOCKETDUCT_TLS_KEY_FILE=/certs/hub.key \
 SOCKETDUCT_AUTH_TOKENS='server-a-starlink:<secret>,server-b-starlink:<secret>,tensorbuzz:<secret>' \
 SOCKETDUCT_REVERSE_GATEWAY_BINDINGS='server-a-starlink:server-a-starlink,server-b-starlink:server-b-starlink' \
 SOCKETDUCT_REVERSE_ROUTE_CLASS_ROUTES='tensorbuzz:starlink:server-a-starlink:docker-a:2375,tensorbuzz:starlink:server-b-starlink:docker-b:2375' \
+SOCKETDUCT_LOG_DIRECTORY=/var/log/socketduct \
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY='<unpadded-base64url-secret>' \
+SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH='2026-09' \
 node src/index.js
 ```
 
@@ -209,6 +252,37 @@ Route-class rows use `username:routeClass:gatewayId:host:port`. If two rows make
 different gateways eligible for the same authenticated class and target, that
 `OPEN` is rejected as ambiguous rather than choosing one implicitly.
 
+When hub logging is enabled, the fingerprint key is mandatory, hub-only, at
+least 32 random bytes encoded as canonical unpadded base64url, and never transmitted or
+logged. Rotate it at least every 30 days. The public epoch label identifies the
+key generation used for a 128-bit role-separated HMAC correlation value.
+
+## Disconnect attribution
+
+Every reverse physical loss has one 128-bit random `disconnectIncidentId` and
+one first local `disconnectReason`. The initial socket error, EOF, peer GOAWAY,
+protocol violation, output limit, replacement, shutdown, or send-after-loss
+cause wins over later close callbacks. The incident records its originating
+component, physical client/gateway role, explicitly named connection
+generations, and fan-out/resume/terminal stream counts. A public RESET code such
+as `RESUME_WINDOW_EXPIRED` classifies the stream outcome; it does not replace
+the physical cause.
+
+The hub propagates its validated incident in RESET/GOAWAY controls and typed
+`SocketductStreamError` / `SocketductSessionLostError` instances. Direct client
+or gateway loss creates and caches an equivalent local incident so concurrent
+stream errors share it, including writes racing the close callback. A new
+authenticated physical clears that cache. Peer-provided reserved attribution
+fields are stripped; peers cannot claim hub origin, inject correlation values,
+or alter named generations.
+
+Terminal, non-resumable hub paths assign the incident before removing their
+bridges, including protocol violations, output overflow, replacement, peer
+GOAWAY, and shutdown. A safe peer GOAWAY code survives as terminal
+classification while the first hub-observed `peer_goaway` cause and hub-created
+incident identity remain authoritative; fatal client and gateway connection
+errors retain that validated attribution.
+
 ## One outbound member per target and route class
 
 Run this once in each target server's route-pinned network namespace, changing
@@ -265,10 +339,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