socketduct 0.1.18 → 0.1.20

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
 
@@ -91,8 +91,8 @@ and automatically rejoin selection. A socket created before readiness is
 returned immediately and waits inside Socketduct with normal callback, event,
 timeout and backpressure behavior; assignment stays FIFO and occurs only on a
 ready member. A virtual socket never changes members.
-Durable process-replacement recovery uses `recoverConnection()` with the
-original gateway ID before the replacement set starts.
+Durable process-replacement recovery uses `recoverConnection()` with exactly
+the original gateway ID or reverse route class before the replacement set starts.
 
 For home Docker hosts behind O2, Zyxel, and Starlink, run
 `OutboundReverseGateway` in each router-pinned namespace and
@@ -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/20260925143000-reverse-client-process-recovery.md

@@ -0,0 +1 @@
+Reverse clients can now recover crash-consistent persistent streams in a replacement process with application-consumption ACKs and a quiescent detach handoff, without reopening the surviving gateway target, while unsupported hub, gateway, and target loss fails closed.

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

@@ -85,12 +85,12 @@ gateway independently for each target `OPEN`, so adding target gateways does not
 multiply client physical connections. Allocation metadata is `routeClass`;
 legacy exact-gateway sets keep `gatewayId` and their existing identity derivation.
 
-Replacement recovery is registered before set startup and addresses the
-original configured gateway ID directly. The set derives the same member
-identity/spool namespace and delegates recovery to that member before any
-physical attempt; round-robin is never involved. An orderly set detach preserves
-active spools while retiring empty warmed lanes. Ordinary new opens cannot name
-a gateway.
+Replacement recovery is registered before set startup and addresses exactly one
+original configured selector: `gatewayId` or `routeClass`. The set derives the
+same member identity/spool namespace and delegates recovery to that member
+before any physical attempt; round-robin is never involved. An orderly set
+detach preserves active spools while retiring empty warmed lanes. Ordinary new
+opens cannot name a member.
 
 Protocol v2 retains the original one-session-per-tunnel architecture for
 rollback. A relay listener selects v2 or v3 explicitly.
@@ -112,9 +112,11 @@ keeps its original target socket and both endpoints durably retain
 unacknowledged send chunks. Replacement physical generations exchange paired
 resume manifests; the hub reconciles receiver-committed sequence positions
 before either side replays. This resumes the same byte stream without reopening
-the target or issuing a second application request. Reverse process replacement
-remains terminal because the original target/app socket objects cannot move to
-a new process.
+the target or issuing a second application request. The Server3 reverse-client
+object/process may be replaced from persistent spool state because the home
+gateway still owns the target socket; the replacement creates a new app-facing
+`VirtualSocket` and resumes from its durable receive ACK. The hub process,
+gateway process, and target socket are not reconstructable by this mechanism.
 
 The hub serializes output independently for each physical destination with a
 bounded queue, so one backpressured target gateway cannot stop client frames

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

@@ -141,9 +141,22 @@ Reverse send replay is persisted before transmission on both the Server3 client
 and outbound gateway. ACKs truncate those private temporary spools. Missing
 targets, expired retention, identity or manifest mismatch, and configured
 buffer/spool/output bounds produce one terminal stream error with the causal
-code. Process-replacement recovery remains unsupported for reverse streams
-because a replacement gateway process cannot inherit the original target TCP
-socket.
+code. A replacement reverse client may restore its generation, selector,
+lifecycle, directional sequences/ACKs, END state, and contiguous send replay
+from persistent spool state before making a physical attempt. It presents the
+durable receive ACK, not the dead object's readable-buffer high-water mark, so
+the surviving gateway conservatively replays any target bytes that were not
+durably acknowledged. A reverse client advances that ACK only after bytes are
+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`.
+
+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
+or FD transfer, target reconnection, and replay after target loss are not
+defined. A fresh gateway that encounters retained bridges submits an empty
+manifest; normal omitted-stream resets retire them without target creation.
 
 Hub output has one ordered owner per physical destination. Frames for a
 backpressured gateway remain in that gateway's bounded queue while frames for
@@ -168,6 +181,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
@@ -503,10 +538,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