socketduct 0.1.18 → 0.1.20

package/src/client/virtual-socket.js

@@ -7,6 +7,7 @@ import {Duplex} from "node:stream"
  * @property {(streamId: number, callback: (error?: Error | null) => void) => void} _endStream - End the writable side.
  * @property {(streamId: number, error: Error | null) => void} _destroyStream - Destroy the virtual stream.
  * @property {(streamId: number) => void} _resumeReadable - Resume inbound flow.
+ * @property {(streamId: number, bytes: number) => void} [_consumeReadable] - Report bytes returned to the application.
  * @property {() => {address?: string, port?: number}} physicalAddress - Current physical endpoint.
  * @property {() => unknown} ref - Reference owner resources.
  * @property {() => unknown} unref - Unreference owner resources.
@@ -14,6 +15,16 @@ import {Duplex} from "node:stream"
 
 /** A stream-local failure where the physical connection may remain usable. */
 export class SocketductStreamError extends Error {
+  /** @type {string | undefined} */ disconnectIncidentId
+  /** @type {string | undefined} */ disconnectReason
+  /** @type {'reverse_hub' | 'reverse_client' | 'reverse_gateway' | undefined} */ incidentOrigin
+  /** @type {'client' | 'gateway' | undefined} */ physicalRole
+  /** @type {number | undefined} */ clientConnectionGeneration
+  /** @type {number | undefined} */ gatewayConnectionGeneration
+  /** @type {number | undefined} */ fanOutCount
+  /** @type {number | undefined} */ resumeSuccessCount
+  /** @type {number | undefined} */ terminalStreamCount
+
   /**
    * @param {string} message - Safe description.
    * @param {string} code - Stable code.
@@ -60,6 +71,9 @@ export class VirtualSocket extends Duplex {
   /** @type {boolean} */
   #remoteEnded = false
 
+  /** @type {number} */
+  #emittedDataBytes = 0
+
   /** @type {boolean} */
   connecting = true
 
@@ -123,6 +137,44 @@ export class VirtualSocket extends Duplex {
     this.#connection._resumeReadable(this.#streamId)
   }
 
+  /**
+   * Reports application consumption after Node has emitted flowing data or
+   * fulfilled a paused-mode read. Owners that need durable receive ACKs can
+   * therefore distinguish consumed bytes from process-local readable bytes.
+   * @param {number} [size] - Requested bytes.
+   * @returns {Buffer | string | null} Readable chunk.
+   * @override
+   */
+  read(size) {
+    const emittedBefore = this.#emittedDataBytes
+    const chunk = super.read(size)
+    if (chunk !== null) {
+      const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
+      const emittedBytes = this.#emittedDataBytes - emittedBefore
+      if (bytes > emittedBytes) this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+    }
+    return chunk
+  }
+
+  /**
+   * A flowing Readable may emit directly from push() without returning a chunk
+   * through read(). Report DATA only after application listeners have run.
+   * @param {string | symbol} event - Event name.
+   * @param {...unknown} args - Event values.
+   * @returns {boolean} Whether the event had listeners.
+   * @override
+   */
+  emit(event, ...args) {
+    const emitted = super.emit(event, ...args)
+    const chunk = args[0]
+    if (event === "data" && (typeof chunk === "string" || Buffer.isBuffer(chunk))) {
+      const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
+      this.#emittedDataBytes += bytes
+      this.#connection._consumeReadable?.(this.#streamId, bytes)
+    }
+    return emitted
+  }
+
   /**
    * @override
    * @param {Buffer | string | Uint8Array} chunk - Application bytes.

package/src/config/environment.js

@@ -1,6 +1,16 @@
 import {isIP} from "node:net"
 
-import {DEFAULT_LOG_MAX_FILE_BYTES, DEFAULT_LOG_MAX_FILES, MAX_LOG_FILES, MIN_LOG_MAX_FILE_BYTES} from "../logging/structured-logger.js"
+import {
+  DEFAULT_LOG_COMPRESSION_LEVEL,
+  DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS,
+  DEFAULT_LOG_CRITICAL_RESERVE_BYTES,
+  DEFAULT_LOG_FLUSH_INTERVAL_MS,
+  DEFAULT_LOG_FRAME_BYTES,
+  DEFAULT_LOG_QUEUE_BYTES,
+  DEFAULT_LOG_RETENTION_BYTES,
+  DEFAULT_LOG_RETENTION_DAYS,
+  DEFAULT_LOG_SEGMENT_BYTES
+} from "../logging/compressed-log-writer.js"
 
 const DEFAULT_RELAY_HOST = "127.0.0.1"
 const DEFAULT_RELAY_PORT = 3100
@@ -52,7 +62,8 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
  * @property {number} handshakeTimeoutMs - Milliseconds to wait for auth after TCP/TLS connect before closing the socket. Default 10000.
  * @property {number} maxInputBytesPerConnection - Per-connection input byte budget before the first authenticated session frame. Default 65536.
  * @property {number} [statusIntervalMs] - Safe status-log interval; zero disables periodic status logs.
- * @property {{directory: string, maxFileBytes: number, maxFiles: number}} [fileLogging] - Optional persistent JSONL logging configuration.
+ * @property {{directory: string, frameMaxBytes: number, flushIntervalMs: number, criticalFlushIntervalMs: number, maxSegmentBytes: number, retentionDays: number, retentionBytes: number, maxQueueBytes: number, criticalReserveBytes: number, compressionLevel: number}} [fileLogging] - Optional durable compressed JSONL logging configuration.
+ * @property {{key: Buffer, keyEpoch: string}} [connectionFingerprint] - Hub-only keyed diagnostic correlation configuration.
  * @property {'auto' | 'off'} [compression] - Whether to negotiate stream.data compression when the runtime supports it. Defaults to auto.
  * @property {2 | 3} [protocolVersion] - Relay wire protocol; defaults to rollback-compatible v2.
  * @property {number} [minCompressBytes] - Payloads smaller than this are sent raw.
@@ -133,13 +144,34 @@ export function loadEnvironmentConfig(env = process.env) {
     ...(env.SOCKETDUCT_REVERSE_HUB_SERVERNAME?.trim() ? {servername: env.SOCKETDUCT_REVERSE_HUB_SERVERNAME.trim()} : {})
   }
   const logDirectory = env.SOCKETDUCT_LOG_DIRECTORY?.trim() || undefined
+  if (env.SOCKETDUCT_LOG_MAX_FILE_BYTES !== undefined || env.SOCKETDUCT_LOG_MAX_FILES !== undefined) throw new Error("SOCKETDUCT_LOG_MAX_FILE_BYTES and SOCKETDUCT_LOG_MAX_FILES were replaced by compressed log frame, segment, and retention settings")
   let fileLogging
   if (logDirectory !== undefined) {
-    const maxFileBytes = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILE_BYTES, "SOCKETDUCT_LOG_MAX_FILE_BYTES", DEFAULT_LOG_MAX_FILE_BYTES)
-    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes < MIN_LOG_MAX_FILE_BYTES) throw new Error(`SOCKETDUCT_LOG_MAX_FILE_BYTES must be a safe integer of at least ${MIN_LOG_MAX_FILE_BYTES}`)
-    const maxFiles = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILES, "SOCKETDUCT_LOG_MAX_FILES", DEFAULT_LOG_MAX_FILES)
-    if (maxFiles > MAX_LOG_FILES) throw new Error(`SOCKETDUCT_LOG_MAX_FILES must be no greater than ${MAX_LOG_FILES}`)
-    fileLogging = {directory: logDirectory, maxFileBytes, maxFiles}
+    const frameMaxBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_FRAME_MAX_BYTES, "SOCKETDUCT_LOG_FRAME_MAX_BYTES", DEFAULT_LOG_FRAME_BYTES, 128, 16 * 1024 * 1024)
+    const flushIntervalMs = parseBoundedInteger(env.SOCKETDUCT_LOG_FLUSH_INTERVAL_MS, "SOCKETDUCT_LOG_FLUSH_INTERVAL_MS", DEFAULT_LOG_FLUSH_INTERVAL_MS, 1, 60_000)
+    const criticalFlushIntervalMs = parseBoundedInteger(env.SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS, "SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS", DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS, 1, 60_000)
+    const maxSegmentBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_SEGMENT_MAX_BYTES, "SOCKETDUCT_LOG_SEGMENT_MAX_BYTES", DEFAULT_LOG_SEGMENT_BYTES, 1024, 4 * 1024 * 1024 * 1024)
+    const retentionDays = parseBoundedInteger(env.SOCKETDUCT_LOG_RETENTION_DAYS, "SOCKETDUCT_LOG_RETENTION_DAYS", DEFAULT_LOG_RETENTION_DAYS, 1, 3650)
+    const retentionBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_RETENTION_MAX_BYTES, "SOCKETDUCT_LOG_RETENTION_MAX_BYTES", DEFAULT_LOG_RETENTION_BYTES, 1024, 1024 * 1024 * 1024 * 1024)
+    const maxQueueBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_QUEUE_MAX_BYTES, "SOCKETDUCT_LOG_QUEUE_MAX_BYTES", DEFAULT_LOG_QUEUE_BYTES, 1024, 1024 * 1024 * 1024)
+    const criticalReserveBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES, "SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES", DEFAULT_LOG_CRITICAL_RESERVE_BYTES, 0, maxQueueBytes - 1)
+    const compressionLevel = parseBoundedInteger(env.SOCKETDUCT_LOG_COMPRESSION_LEVEL, "SOCKETDUCT_LOG_COMPRESSION_LEVEL", DEFAULT_LOG_COMPRESSION_LEVEL, 1, 22)
+    if (maxQueueBytes - criticalReserveBytes < 512) throw new Error("SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES must leave at least 512 noncritical queue bytes")
+    if (maxSegmentBytes > retentionBytes) throw new Error("SOCKETDUCT_LOG_SEGMENT_MAX_BYTES must not exceed SOCKETDUCT_LOG_RETENTION_MAX_BYTES")
+    fileLogging = {directory: logDirectory, frameMaxBytes, flushIntervalMs, criticalFlushIntervalMs, maxSegmentBytes, retentionDays, retentionBytes, maxQueueBytes, criticalReserveBytes, compressionLevel}
+  }
+  const fingerprintKeyText = env.SOCKETDUCT_CONNECTION_FINGERPRINT_KEY?.trim() || undefined
+  const fingerprintKeyEpoch = env.SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH?.trim() || undefined
+  if (mode !== "reverse-hub" && (fingerprintKeyText !== undefined || fingerprintKeyEpoch !== undefined)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY is hub-only")
+  if ((fingerprintKeyText === undefined) !== (fingerprintKeyEpoch === undefined)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY and SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH must be supplied together")
+  if (mode === "reverse-hub" && fileLogging !== undefined && fingerprintKeyText === undefined) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY is required for reverse-hub persistent logging")
+  let connectionFingerprint
+  if (fingerprintKeyText !== undefined && fingerprintKeyEpoch !== undefined) {
+    if (!/^[A-Za-z0-9_-]+$/.test(fingerprintKeyText)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY must be unpadded base64url")
+    const key = Buffer.from(fingerprintKeyText, "base64url")
+    if (key.length < 32 || key.toString("base64url") !== fingerprintKeyText) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY must encode at least 32 bytes")
+    if (!/^[A-Za-z0-9_-]{1,32}$/.test(fingerprintKeyEpoch)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH must be 1-32 URL-safe characters")
+    connectionFingerprint = {key, keyEpoch: fingerprintKeyEpoch}
   }
 
   return {
@@ -184,6 +216,7 @@ export function loadEnvironmentConfig(env = process.env) {
       DEFAULT_STATUS_INTERVAL_MS
     ),
     ...(fileLogging === undefined ? {} : {fileLogging}),
+    ...(connectionFingerprint === undefined ? {} : {connectionFingerprint}),
     compression,
     protocolVersion,
     minCompressBytes: parsePositiveInteger(
@@ -343,6 +376,22 @@ function parseNonNegativeInteger(value, name, defaultValue) {
   return parsed
 }
 
+/**
+ * Parses one bounded integer environment setting.
+ * @param {string | undefined} value - Raw value.
+ * @param {string} name - Environment variable name.
+ * @param {number} defaultValue - Default value.
+ * @param {number} minimum - Inclusive minimum.
+ * @param {number} maximum - Inclusive maximum.
+ * @returns {number} Parsed bounded integer.
+ */
+function parseBoundedInteger(value, name, defaultValue, minimum, maximum) {
+  if (value === undefined || value === "") return defaultValue
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`)
+  return parsed
+}
+
 /**
  * @param {string} value - Comma-separated username:token entries.
  * @returns {StaticTokenConfig[]} Parsed static tokens.

package/src/index.js

@@ -1,10 +1,11 @@
 import {loadEnvironmentConfig} from "./config/environment.js"
-import {createJsonlFileLogger} from "./logging/structured-logger.js"
+import {createCompressedJsonlFileLogger} from "./logging/compressed-log-writer.js"
 import {startRelayRuntime} from "./server/relay-runtime.js"
 import {startOutboundReverseGatewayRuntime, startReverseHubRuntime} from "./reverse/runtime.js"
 
 export {createSocketductConnectionFactory} from "./client/connect.js"
 export {createJsonlFileLogger, createStructuredLogger} from "./logging/structured-logger.js"
+export {createCompressedJsonlFileLogger, CompressedJsonlFileLogger} from "./logging/compressed-log-writer.js"
 export {SocketductHttpAgent} from "./client/http-agent.js"
 export {connectSocketduct, SocketductRelayError, SocketductSocket} from "./client/socketduct-socket.js"
 export {createMultiplexedSocketductConnection, MultiplexedSocketductConnection} from "./client/multiplexed-connection.js"
@@ -33,11 +34,12 @@ export function getStartupSummary() {
  */
 async function main() {
   const config = loadEnvironmentConfig()
-  const logger = config.fileLogging === undefined ? undefined : createJsonlFileLogger({...config.fileLogging, role: config.mode})
+  const logger = config.fileLogging === undefined ? undefined : createCompressedJsonlFileLogger({...config.fileLogging, role: config.mode})
   if (config.mode === "summary") {
     const summary = getStartupSummary()
     console.log(`${summary.name} starting in ${summary.mode} mode on ${summary.runtime}`)
-    logger?.log("process.started", {runtimeMode: config.mode})
+    logger?.log("process.started", {runtimeMode: config.mode, ...loggingConfigurationFields(config.fileLogging)})
+    await logger?.close()
     return
   }
 
@@ -45,31 +47,29 @@ async function main() {
   let service
   /** @type {() => Promise<void>} */
   let closeRuntime
-  if (config.mode === "relay") {
-    const runtime = await startRelayRuntime(config)
-    service = runtime.relay
-    closeRuntime = runtime.close
-  } else if (config.mode === "reverse-hub") {
-    const runtime = await startReverseHubRuntime(config)
-    service = runtime.hub
-    closeRuntime = runtime.close
-  } else {
-    const runtime = await startOutboundReverseGatewayRuntime(config, logger)
-    service = runtime.gateway
-    closeRuntime = runtime.close
+  try {
+    if (config.mode === "relay") {
+      const runtime = await startRelayRuntime(config)
+      service = runtime.relay
+      closeRuntime = runtime.close
+    } else if (config.mode === "reverse-hub") {
+      const runtime = await startReverseHubRuntime(config, logger)
+      service = runtime.hub
+      closeRuntime = runtime.close
+    } else {
+      const runtime = await startOutboundReverseGatewayRuntime(config, logger)
+      service = runtime.gateway
+      closeRuntime = runtime.close
+    }
+  } catch (startupError) {
+    try {
+      await logger?.close()
+    } catch (loggerError) {
+      throw new AggregateError([startupError, loggerError], "Socketduct startup and diagnostic logger shutdown both failed", {cause: loggerError})
+    }
+    throw startupError
   }
   const tlsStatus = config.mode === "relay" && config.relayTls === undefined ? "plaintext" : "TLS"
-  console.log(JSON.stringify({
-    event: `${config.mode}.started`,
-    ...(config.mode === "reverse-gateway" ? {gatewayId: config.reverseGatewayId} : {host: config.relayHost, port: service.port}),
-    transportSecurity: tlsStatus,
-    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
-  }))
-  logger?.log("process.started", {
-    runtimeMode: config.mode,
-    transportSecurity: tlsStatus,
-    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
-  })
   const statusIntervalMs = config.statusIntervalMs ?? 30_000
   const statusTimer = statusIntervalMs > 0
     ? setInterval(() => {
@@ -80,9 +80,15 @@ async function main() {
     : undefined
   statusTimer?.unref()
 
+  let shuttingDown = false
   const shutdown = () => {
+    if (shuttingDown) return
+    shuttingDown = true
     if (statusTimer !== undefined) clearInterval(statusTimer)
     closeRuntime()
+      .then(() => { logger?.log("process.stopped", {runtimeMode: config.mode}) })
+      .then(() => logger?.flush())
+      .then(() => logger?.close())
       .then(() => process.exit(0))
       .catch((error) => {
         console.error(error)
@@ -91,6 +97,38 @@ async function main() {
   }
   process.once("SIGINT", shutdown)
   process.once("SIGTERM", shutdown)
+  logger?.log("process.started", {
+    runtimeMode: config.mode,
+    transportSecurity: tlsStatus,
+    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression,
+    ...loggingConfigurationFields(config.fileLogging)
+  })
+  console.log(JSON.stringify({
+    event: `${config.mode}.started`,
+    ...(config.mode === "reverse-gateway" ? {gatewayId: config.reverseGatewayId} : {host: config.relayHost, port: service.port}),
+    transportSecurity: tlsStatus,
+    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
+  }))
+}
+
+/**
+ * Returns only non-sensitive effective logger settings for the startup record.
+ * @param {import('./config/environment.js').RelayEnvironmentConfig['fileLogging']} fileLogging - Managed sink settings.
+ * @returns {Record<string, number>} Safe numeric settings.
+ */
+function loggingConfigurationFields(fileLogging) {
+  if (fileLogging === undefined) return {}
+  return {
+    frameMaxBytes: fileLogging.frameMaxBytes,
+    flushIntervalMs: fileLogging.flushIntervalMs,
+    criticalFlushIntervalMs: fileLogging.criticalFlushIntervalMs,
+    maxSegmentBytes: fileLogging.maxSegmentBytes,
+    retentionDays: fileLogging.retentionDays,
+    retentionBytes: fileLogging.retentionBytes,
+    maxQueueBytes: fileLogging.maxQueueBytes,
+    criticalReserveBytes: fileLogging.criticalReserveBytes,
+    compressionLevel: fileLogging.compressionLevel
+  }
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/src/logging/compressed-log-reader.js

@@ -0,0 +1,256 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
+import {createHash} from "node:crypto"
+import {constants} from "node:fs"
+import {lstat, open, readdir, stat} from "node:fs/promises"
+import {join} from "node:path"
+
+import {inspectLogBatch} from "./log-batch.js"
+import {INDEX_ENTRY_BYTES, INDEX_HEADER_BYTES, parseIndexEntry, parseIndexHeader, uuidBytes} from "./log-segment-index.js"
+import {decompressLogFrame} from "./zstd-frame-codec.js"
+
+const SEGMENT_NAME = /^([a-z][a-z0-9-]{0,63})-([A-Za-z0-9_-]{22})-([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})\.jsonl\.zst$/
+const DEFAULT_MAX_DECODED_FRAME_BYTES = 16 * 1024 * 1024
+
+/** Incremental durable-index reader for long-running tail consumers. */
+export class CompressedLogTailReader {
+  /** @type {string} */ #directory
+  /** @type {{filters?: Record<string, unknown>, maxDecodedFrameBytes?: number}} */ #options
+  /** @type {Map<string, {nextEntry: number, expectedSequence: bigint | undefined, expectedOffset: bigint, sealed: boolean}>} */ #segments = new Map()
+  /** @type {number} */ #decodedFrames = 0
+
+  /**
+   * @param {string} directory - Private compressed-log directory.
+   * @param {{filters?: Record<string, unknown>, maxDecodedFrameBytes?: number}} [options] - Read policy.
+   */
+  constructor(directory, options = {}) {
+    if (typeof directory !== "string" || directory.length === 0) throw new TypeError("compressed log directory is required")
+    this.#directory = directory
+    this.#options = options
+  }
+
+  /** Reads only index entries committed since the prior poll. */
+  async poll() {
+    await assertPrivateDirectory(this.#directory)
+    const entries = (await readdir(this.#directory)).filter((entry) => entry.endsWith(".jsonl.zst")).sort()
+    const present = new Set(entries)
+    for (const name of this.#segments.keys()) if (!present.has(name)) this.#segments.delete(name)
+    /** @type {Array<Record<string, unknown>>} */
+    const records = []
+    /** @type {Array<{segment: string, code: string}>} */
+    const errors = []
+    for (const entry of entries) {
+      const previous = this.#segments.get(entry)
+      if (previous?.sealed === true) continue
+      try {
+        const result = await readCompressedLogSegmentIncremental(join(this.#directory, entry), this.#options, previous)
+        this.#segments.set(entry, result.cursor)
+        this.#decodedFrames = Math.min(Number.MAX_SAFE_INTEGER, this.#decodedFrames + result.decodedFrames)
+        records.push(...result.records)
+      } catch (error) {
+        if (evidenceErrorCode(error) === "ENOENT") {
+          this.#segments.delete(entry)
+          continue
+        }
+        errors.push({segment: entry, code: evidenceErrorCode(error)})
+      }
+    }
+    records.sort(compareRecords)
+    const filtered = this.#options.filters === undefined ? records : records.filter((record) => matchesFilters(record, this.#options.filters ?? {}))
+    return {records: filtered, incomplete: errors.length > 0, errors}
+  }
+
+  /** Returns bounded cursor count and cumulative decode work for health/tests. */
+  status() { return {trackedSegments: this.#segments.size, decodedFrames: this.#decodedFrames} }
+}
+
+/**
+ * Reads and validates every durable indexed frame, preserving evidence errors.
+ * @param directory
+ * @param options
+ */
+export async function readCompressedLogDirectory(/** @type {string} */ directory, /** @type {{filters?: Record<string, unknown>, maxDecodedFrameBytes?: number}} */ options = {}) {
+  await assertPrivateDirectory(directory)
+  const entries = await readdir(directory)
+  /** @type {Array<Record<string, unknown>>} */
+  const records = []
+  /** @type {Array<{segment: string, code: string}>} */
+  const errors = []
+  for (const entry of entries.sort()) {
+    if (!entry.endsWith(".jsonl.zst")) continue
+    try {
+      const selected = await readCompressedLogSegment(join(directory, entry), options)
+      records.push(...selected)
+    } catch (error) {
+      errors.push({segment: entry, code: evidenceErrorCode(error)})
+    }
+  }
+  records.sort(compareRecords)
+  const filtered = options.filters === undefined ? records : records.filter((record) => matchesFilters(record, options.filters ?? {}))
+  return {records: filtered, incomplete: errors.length > 0, errors}
+}
+
+/**
+ * Reads one segment frame-by-frame from its durable index.
+ * @param dataPath
+ * @param options
+ */
+export async function readCompressedLogSegment(/** @type {string} */ dataPath, /** @type {{maxDecodedFrameBytes?: number}} */ options = {}) {
+  return (await readCompressedLogSegmentIncremental(dataPath, options)).records
+}
+
+/**
+ * Reads newly indexed frames from one segment and advances its validated cursor.
+ * @param {string} dataPath - Segment data path.
+ * @param {{maxDecodedFrameBytes?: number}} options - Decode bounds.
+ * @param {{nextEntry: number, expectedSequence: bigint | undefined, expectedOffset: bigint, sealed: boolean}} [cursor] - Prior cursor.
+ */
+async function readCompressedLogSegmentIncremental(dataPath, options, cursor = undefined) {
+  const name = dataPath.slice(dataPath.lastIndexOf("/") + 1)
+  const match = SEGMENT_NAME.exec(name)
+  if (match === null) throw evidenceError("INVALID_SEGMENT_NAME")
+  const writerEpoch = Buffer.from(/** @type {string} */ (match[2]), "base64url")
+  const segmentUuid = uuidBytes(/** @type {string} */ (match[3]))
+  if (writerEpoch.length !== 16) throw evidenceError("INVALID_WRITER_EPOCH")
+  const indexPath = `${dataPath}.idx`
+  if (await pathExists(`${dataPath}.quarantine`)) throw evidenceError("LOG_EVIDENCE_QUARANTINED")
+  await Promise.all([assertPrivateRegularFile(dataPath), assertPrivateRegularFile(indexPath)])
+  const [dataHandle, indexHandle] = await Promise.all([
+    open(dataPath, constants.O_RDONLY | constants.O_NOFOLLOW),
+    open(indexPath, constants.O_RDONLY | constants.O_NOFOLLOW)
+  ])
+  try {
+    const [dataStats, indexStats] = await Promise.all([dataHandle.stat(), indexHandle.stat()])
+    if (indexStats.size < INDEX_HEADER_BYTES) throw evidenceError("INDEX_HEADER_TORN")
+    const headerBytes = Buffer.alloc(INDEX_HEADER_BYTES)
+    await readExactly(indexHandle, headerBytes, 0)
+    const header = parseIndexHeader(headerBytes)
+    if (!header.segmentUuid.equals(segmentUuid) || !header.writerEpoch.equals(writerEpoch)) throw evidenceError("INDEX_IDENTITY_MISMATCH")
+    const completeEntryBytes = indexStats.size - INDEX_HEADER_BYTES
+    const sealed = await pathExists(`${dataPath}.sealed`)
+    if (completeEntryBytes % INDEX_ENTRY_BYTES !== 0 && sealed) throw evidenceError("INDEX_TAIL_TORN")
+    const entryCount = Math.floor(completeEntryBytes / INDEX_ENTRY_BYTES)
+    const nextEntry = cursor?.nextEntry ?? 0
+    if (!Number.isSafeInteger(nextEntry) || nextEntry < 0 || nextEntry > entryCount) throw evidenceError("INDEX_CURSOR_INVALID")
+    /** @type {Array<Record<string, unknown>>} */
+    const records = []
+    let expectedSequence = cursor?.expectedSequence
+    let expectedOffset = cursor?.expectedOffset ?? 0n
+    let decodedFrames = 0
+    for (let index = nextEntry; index < entryCount; index += 1) {
+      const entryBytes = Buffer.alloc(INDEX_ENTRY_BYTES)
+      await readExactly(indexHandle, entryBytes, INDEX_HEADER_BYTES + index * INDEX_ENTRY_BYTES)
+      const entry = parseIndexEntry(entryBytes, {segmentUuid, writerEpoch})
+      if (expectedSequence !== undefined && entry.firstSequence !== expectedSequence) throw evidenceError("INDEX_SEQUENCE_GAP")
+      if (entry.dataOffset !== expectedOffset) throw evidenceError("INDEX_DATA_GAP")
+      if (entry.dataOffset + entry.compressedLength > BigInt(dataStats.size)) throw evidenceError("INDEX_DATA_BOUNDS")
+      if (entry.compressedLength > BigInt(Number.MAX_SAFE_INTEGER) || entry.uncompressedLength > BigInt(options.maxDecodedFrameBytes ?? DEFAULT_MAX_DECODED_FRAME_BYTES)) throw evidenceError("FRAME_SIZE_LIMIT")
+      const frame = Buffer.alloc(Number(entry.compressedLength))
+      await readExactly(dataHandle, frame, Number(entry.dataOffset))
+      if (!createHash("sha256").update(frame).digest().equals(entry.frameSha256)) throw evidenceError("FRAME_HASH_MISMATCH")
+      const raw = await decompressLogFrame(frame)
+      if (BigInt(raw.length) !== entry.uncompressedLength) throw evidenceError("FRAME_LENGTH_MISMATCH")
+      const inspected = inspectLogBatch(raw, writerEpoch)
+      if (inspected.firstSequence !== entry.firstSequence || inspected.lastSequence !== entry.lastSequence || inspected.recordCount !== entry.recordCount || inspected.minTimestamp !== entry.minTimestamp || inspected.maxTimestamp !== entry.maxTimestamp || !inspected.batchId.equals(entry.batchId)) throw evidenceError("FRAME_METADATA_MISMATCH")
+      records.push(...inspected.records)
+      decodedFrames += 1
+      expectedSequence = entry.lastSequence + 1n
+      expectedOffset = entry.dataOffset + entry.compressedLength
+    }
+    if (sealed && expectedOffset !== BigInt(dataStats.size)) throw evidenceError("SEALED_DATA_TAIL")
+    return {records, decodedFrames, cursor: {nextEntry: entryCount, expectedSequence, expectedOffset, sealed}}
+  } finally {
+    await Promise.allSettled([dataHandle.close(), indexHandle.close()])
+  }
+}
+
+/**
+ * @param {import('node:fs/promises').FileHandle} handle - Open file. @param {Buffer} buffer - Exact destination. @param {number} position - File position.
+ * @param buffer
+ * @param position
+ */
+async function readExactly(handle, buffer, position) {
+  let offset = 0
+  while (offset < buffer.length) {
+    const {bytesRead} = await handle.read(buffer, offset, buffer.length - offset, position + offset)
+    if (bytesRead === 0) throw evidenceError("SHORT_READ")
+    offset += bytesRead
+  }
+}
+
+/**
+ *
+ * @param path
+ */
+async function assertPrivateDirectory(/** @type {string} */ path) {
+  const stats = await lstat(path)
+  if (!stats.isDirectory() || (stats.mode & 0o777) !== 0o700) throw evidenceError("UNSAFE_LOG_DIRECTORY")
+}
+
+/**
+ *
+ * @param path
+ */
+async function assertPrivateRegularFile(/** @type {string} */ path) {
+  const stats = await lstat(path)
+  if (!stats.isFile() || (stats.mode & 0o777) !== 0o600) throw evidenceError("UNSAFE_LOG_FILE")
+}
+
+/**
+ *
+ * @param path
+ */
+async function pathExists(/** @type {string} */ path) {
+  try { await stat(path); return true } catch (error) { if (error !== null && typeof error === "object" && /** @type {{code?: unknown}} */ (error).code === "ENOENT") return false; throw error }
+}
+
+/**
+ *
+ * @param record
+ * @param filters
+ */
+function matchesFilters(/** @type {Record<string, unknown>} */ record, /** @type {Record<string, unknown>} */ filters) {
+  const mappings = {
+    event: "event",
+    incident: "disconnectIncidentId",
+    gateway: "gatewayId",
+    routeClass: "routeClass",
+    clientGeneration: "clientConnectionGeneration",
+    gatewayGeneration: "gatewayConnectionGeneration",
+    reason: "disconnectReason"
+  }
+  for (const [filter, field] of Object.entries(mappings)) if (filters[filter] !== undefined && String(record[field]) !== String(filters[filter])) return false
+  const timestamp = typeof record.timestamp === "string" ? Date.parse(record.timestamp) : Number.NaN
+  if (filters.since !== undefined && timestamp < /** @type {number} */ (filters.since)) return false
+  if (filters.until !== undefined && timestamp > /** @type {number} */ (filters.until)) return false
+  return true
+}
+
+/**
+ *
+ * @param left
+ * @param right
+ */
+function compareRecords(/** @type {Record<string, unknown>} */ left, /** @type {Record<string, unknown>} */ right) {
+  const time = String(left.timestamp).localeCompare(String(right.timestamp))
+  if (time !== 0) return time
+  const leftEpoch = Buffer.from(String(left.writerEpoch), "base64url")
+  const rightEpoch = Buffer.from(String(right.writerEpoch), "base64url")
+  const epoch = Buffer.compare(leftEpoch, rightEpoch)
+  return epoch !== 0 ? epoch : BigInt(String(left.eventSequence)) < BigInt(String(right.eventSequence)) ? -1 : BigInt(String(left.eventSequence)) > BigInt(String(right.eventSequence)) ? 1 : 0
+}
+
+/**
+ *
+ * @param error
+ */
+function evidenceErrorCode(/** @type {unknown} */ error) {
+  return error !== null && typeof error === "object" && typeof /** @type {{code?: unknown}} */ (error).code === "string" ? /** @type {{code: string}} */ (error).code : "LOG_EVIDENCE_INVALID"
+}
+
+/**
+ *
+ * @param code
+ */
+function evidenceError(/** @type {string} */ code) {
+  return Object.assign(new Error("Compressed log evidence is incomplete or corrupt"), {code})
+}