socketduct 0.1.19 → 0.1.20

package/src/cli/socketduct.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/no-undefined-types, jsdoc/require-param-type, jsdoc/require-returns */
+import {once} from "node:events"
+
+import {CompressedLogTailReader, readCompressedLogDirectory} from "../logging/compressed-log-reader.js"
+
+const FILTER_OPTIONS = new Map([
+  ["--event", "event"],
+  ["--incident", "incident"],
+  ["--gateway", "gateway"],
+  ["--route-class", "routeClass"],
+  ["--client-generation", "clientGeneration"],
+  ["--gateway-generation", "gatewayGeneration"],
+  ["--reason", "reason"],
+  ["--since", "since"],
+  ["--until", "until"]
+])
+
+/** @typedef {{kind: 'search' | 'tail', directory: string, filters: Record<string, unknown>, follow: boolean, pollMs: number}} LogCommand */
+
+/**
+ *
+ * @param argv
+ * @param streams
+ */
+export async function runSocketductCli(/** @type {string[]} */ argv, /** @type {{stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream}} */ streams = {}) {
+  const stdout = streams.stdout ?? process.stdout
+  const stderr = streams.stderr ?? process.stderr
+  try {
+    const command = parseArguments(argv)
+    if (command.kind === "search") {
+      const result = await readCompressedLogDirectory(command.directory, {filters: command.filters})
+      if (result.incomplete) {
+        await writeOutput(stderr, `Socketduct log evidence error (${result.errors[0]?.code ?? "LOG_EVIDENCE_INVALID"})\n`)
+        return 2
+      }
+      for (const record of result.records) await writeOutput(stdout, `${JSON.stringify(record)}\n`)
+      return result.records.length > 0 ? 0 : 1
+    }
+    const reader = new CompressedLogTailReader(command.directory, {filters: command.filters})
+    let stopping = false
+    const stop = () => { stopping = true }
+    if (command.follow) {
+      process.once("SIGINT", stop)
+      process.once("SIGTERM", stop)
+    }
+    try {
+      do {
+        const result = await reader.poll()
+        if (result.incomplete) {
+          await writeOutput(stderr, `Socketduct log evidence error (${result.errors[0]?.code ?? "LOG_EVIDENCE_INVALID"})\n`)
+          return 2
+        }
+        for (const record of result.records) {
+          await writeOutput(stdout, `${JSON.stringify(record)}\n`)
+        }
+        if (command.follow && !stopping) await waitForPoll(command.pollMs)
+      } while (command.follow && !stopping)
+      return 0
+    } finally {
+      if (command.follow) {
+        process.off("SIGINT", stop)
+        process.off("SIGTERM", stop)
+      }
+    }
+  } catch {
+    await writeOutput(stderr, "Socketduct logs error (INVALID_ARGUMENT_OR_IO)\n")
+    return 2
+  }
+}
+
+/** @param {string[]} argv - CLI arguments. @returns {LogCommand} */
+function parseArguments(argv) {
+  if (argv[0] !== "logs" || (argv[1] !== "search" && argv[1] !== "tail")) throw new Error("Expected logs search or logs tail")
+  const kind = argv[1]
+  let directory
+  let follow = false
+  let pollMs = 250
+  /** @type {Record<string, unknown>} */
+  const filters = {}
+  for (let index = 2; index < argv.length; index += 1) {
+    const option = argv[index]
+    if (option === undefined) throw new Error("Missing option")
+    if (option === "--follow" && kind === "tail") { follow = true; continue }
+    const value = argv[++index]
+    if (value === undefined || value.length === 0) throw new Error("Missing option value")
+    if (option === "--directory") { directory = value; continue }
+    if (option === "--poll-ms" && kind === "tail") {
+      pollMs = positiveInteger(value, "poll interval")
+      if (pollMs > 60_000) throw new Error("Poll interval exceeds 60000 milliseconds")
+      continue
+    }
+    const filter = FILTER_OPTIONS.get(option)
+    if (filter === undefined) throw new Error("Unknown logs option")
+    filters[filter] = validateFilter(filter, value)
+  }
+  if (directory === undefined) throw new Error("Log directory is required")
+  return {kind, directory, filters, follow, pollMs}
+}
+
+/**
+ * @param {string} filter - Internal filter name. @param {string} value - User input. @returns {string | number}
+ * @param value
+ */
+function validateFilter(filter, value) {
+  if (filter === "clientGeneration" || filter === "gatewayGeneration") return positiveInteger(value, "connection generation", true)
+  if (filter === "since" || filter === "until") {
+    const timestamp = Date.parse(value)
+    if (!Number.isSafeInteger(timestamp)) throw new Error("Invalid time filter")
+    return timestamp
+  }
+  if (filter === "incident" && !/^[A-Za-z0-9_-]{22}$/.test(value)) throw new Error("Invalid incident filter")
+  if ((filter === "gateway" || filter === "routeClass") && !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) throw new Error("Invalid route filter")
+  if ((filter === "event" || filter === "reason") && !/^[a-zA-Z][a-zA-Z0-9_.-]{0,95}$/.test(value)) throw new Error("Invalid diagnostic filter")
+  return value
+}
+
+/**
+ * @param {string} value - User input. @param {string} name - Setting name. @param {boolean} [allowZero] - Whether zero is valid.
+ * @param name
+ * @param allowZero
+ */
+function positiveInteger(value, name, allowZero = false) {
+  if (!/^(?:0|[1-9][0-9]*)$/.test(value)) throw new Error(`Invalid ${name}`)
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || (allowZero ? parsed < 0 : parsed < 1)) throw new Error(`Invalid ${name}`)
+  return parsed
+}
+
+/**
+ * @param {NodeJS.WriteStream} stream - Output stream. @param {string} text - Text to write.
+ * @param text
+ */
+async function writeOutput(stream, text) {
+  if (!stream.write(text)) await once(stream, "drain")
+}
+
+/** @param {number} milliseconds - Poll interval. */
+async function waitForPoll(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exitCode = await runSocketductCli(process.argv.slice(2))

package/src/client/virtual-socket.js

@@ -15,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.

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})
+}