socketduct 0.1.15

package/src/logging/structured-logger.js

@@ -0,0 +1,745 @@
+import {appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, renameSync, statSync, unlinkSync} from "node:fs"
+import {join} from "node:path"
+
+export const DEFAULT_LOG_MAX_FILE_BYTES = 10 * 1024 * 1024
+export const DEFAULT_LOG_MAX_FILES = 5
+export const MIN_LOG_MAX_FILE_BYTES = 1024
+export const MAX_LOG_FILES = 100
+
+const MAX_JSONL_BYTES = 1024
+const MAX_GATEWAY_ID_BYTES = 64
+const MAX_ERROR_NAME_BYTES = 96
+const MAX_ERROR_MESSAGE_BYTES = 512
+const MAX_ERROR_STACK_BYTES = 512
+const ERROR_DETAILS = Symbol("errorDetails")
+const ROLE = /^[a-z][a-z0-9-]{0,63}$/
+const GATEWAY_ID = /^[A-Za-z0-9_-]+$/
+const RUNTIME_MODES = new Set(["summary", "relay", "reverse-hub", "reverse-gateway"])
+const TRANSPORT_SECURITY = new Set(["plaintext", "TLS"])
+const COMPRESSION = new Set(["auto", "off", "zstd", "none"])
+const STATES = new Set(["configured", "connecting", "registering", "ready", "reconnecting", "disconnected", "closed", "starting", "degraded", "failed"])
+const SAFE_ERROR_CODES = new Set([
+  "AUTH_FAILED",
+  "AUTH_NEGOTIATION_FAILED",
+  "AUTH_OWNERSHIP_MISMATCH",
+  "AUTH_REQUIRED",
+  "BUFFER_LIMIT",
+  "CONNECTION_REJECTED",
+  "CONNECTION_RESUME_LOST",
+  "ECONNABORTED",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EPIPE",
+  "ETIMEDOUT",
+  "GATEWAY_DISCONNECTED",
+  "GATEWAY_REGISTRATION_FAILED",
+  "GATEWAY_REPLACED",
+  "GATEWAY_SELECTION_FAILED",
+  "GATEWAY_STREAM_LIMIT",
+  "GATEWAY_UNAVAILABLE",
+  "HANDSHAKE_TIMEOUT",
+  "HUB_SHUTDOWN",
+  "INPUT_LIMIT_EXCEEDED",
+  "INVALID_STREAM_OPEN",
+  "PROTOCOL_NEGOTIATION_FAILED",
+  "PROTOCOL_VIOLATION",
+  "RECONNECT_EXHAUSTED",
+  "RESUME_REJECTED",
+  "RESUME_SESSION_LOST",
+  "SESSION_LOST",
+  "SOCKETDUCT_AUTH_TIMEOUT",
+  "SOCKETDUCT_BUFFER_LIMIT",
+  "SOCKETDUCT_CONNECTION_CLOSED",
+  "SOCKETDUCT_GATEWAY_CLOSED",
+  "SOCKETDUCT_MEMBER_TERMINAL",
+  "SOCKETDUCT_SET_BUFFER_LIMIT",
+  "SOCKETDUCT_SET_PENDING_OPEN_LIMIT",
+  "SOCKETDUCT_SET_QUEUE_LIMIT",
+  "SOCKETDUCT_SET_SPOOL_LIMIT",
+  "SOCKETDUCT_TRANSPORT_SET_CLOSED",
+  "SOCKETDUCT_TRANSPORT_SET_NOT_READY",
+  "SOCKETDUCT_TRANSPORT_SET_TERMINAL",
+  "STALE_GENERATION",
+  "STREAM_RESET",
+  "TARGET_CLOSED",
+  "TARGET_OPEN_FAILED",
+  "TARGET_OPEN_TIMEOUT",
+  "TARGET_READ_FAILED",
+  "TARGET_UNAUTHORIZED",
+  "TLS_ERROR",
+  "TRANSPORT_CLOSED",
+  "UNKNOWN"
+])
+const NUMBER_FIELDS = new Set([
+  "activeTargets",
+  "activeTunnels",
+  "attachedSessions",
+  "attempt",
+  "authenticatedConnections",
+  "bufferedBytes",
+  "bufferedTargetBytes",
+  "bufferLimitBytes",
+  "clientPhysicalConnections",
+  "closedMembers",
+  "compressionBytesSaved",
+  "configuredMembers",
+  "connectingMembers",
+  "connectionGeneration",
+  "connectionIdentities",
+  "controlQueuedBytes",
+  "dataQueuedBytes",
+  "degradedMembers",
+  "delayMs",
+  "detachedSessions",
+  "gatewayPhysicalConnections",
+  "gatewayRegistrations",
+  "generation",
+  "healthyGateways",
+  "maxPendingOpens",
+  "minimumReadyMembers",
+  "openFailures",
+  "pendingOpens",
+  "physicalAccepts",
+  "physicalConnections",
+  "physicalConnects",
+  "queuedBytes",
+  "rawDataBytes",
+  "readyMembers",
+  "reconnectAttempts",
+  "reconnectSuccesses",
+  "registeredGateways",
+  "rejectedOpens",
+  "rejectedRegistrations",
+  "retainedClientIdentities",
+  "resets",
+  "resumeFailures",
+  "resumeSuccesses",
+  "sessions",
+  "spoolBytes",
+  "spoolCleanupFailures",
+  "streamId",
+  "streamOpenLatencyMs",
+  "targetConnectionAttempts",
+  "targetOpenFailures",
+  "targetOpens",
+  "targetRetryTimers",
+  "virtualOpens",
+  "virtualStreams",
+  "wireDataBytes"
+])
+const RUNTIME_STATUS_FIELDS = new Set([...NUMBER_FIELDS, "compression", "physicalState"])
+const EVENT_FIELDS = new Map([
+  ["process.started", new Set(["runtimeMode", "transportSecurity", "compression"])],
+  ["runtime.status", RUNTIME_STATUS_FIELDS],
+  ["transport.connecting", new Set(["generation", "attempt", "gatewayId", "reconnect"])],
+  ["transport.connected", new Set(["generation", "attempt", "gatewayId", "physicalConnects", "reconnect"])],
+  ["transport.disconnected", new Set(["generation", "gatewayId", "virtualStreams", "errorCode"])],
+  ["transport.reconnect_scheduled", new Set(["generation", "attempt", "delayMs", "gatewayId", "errorCode"])],
+  ["transport.reconnect_succeeded", new Set(["generation", "attempt", "gatewayId", "physicalConnects"])],
+  ["transport.failed", new Set(["generation", "attempt", "gatewayId", "errorCode"])],
+  ["transport_set.started", new Set(["configuredMembers", "minimumReadyMembers"])],
+  ["transport_set.ready", new Set(["configuredMembers", "readyMembers", "minimumReadyMembers"])],
+  ["transport_set.member_state", new Set(["gatewayId", "state", "generation", "physicalConnects", "reconnectAttempts", "errorCode"])],
+  ["transport_set.member_replaced", new Set(["gatewayId", "generation", "physicalConnects"])],
+  ["transport_set.terminal_failure", new Set(["configuredMembers", "closedMembers", "errorCode"])],
+  ["virtual_stream.opening", new Set(["streamId", "generation", "gatewayId", "recovered"])],
+  ["virtual_stream.opened", new Set(["streamId", "generation", "gatewayId", "recovered"])],
+  ["virtual_stream.closed", new Set(["streamId", "generation", "gatewayId"])],
+  ["virtual_stream.error", new Set(["streamId", "generation", "gatewayId", "errorCode"])],
+  ["reverse_gateway.target_opened", new Set(["streamId", "generation", "gatewayId"])],
+  ["reverse_gateway.target_open_failed", new Set(["streamId", "generation", "gatewayId", "errorCode"])],
+  ["reverse_gateway.target_closed", new Set(["streamId", "generation", "gatewayId", "errorCode"])]
+])
+const FAILED_LOGGERS = new WeakSet()
+
+/**
+ * @typedef {object} DiagnosticLogger
+ * @property {(event: string, fields?: Record<string, unknown>) => void} log - Records one diagnostic event.
+ * @typedef {object} StructuredLoggerOptions
+ * @property {string} role - Stable process/component role.
+ * @property {(line: string) => unknown} writeLine - Receives one complete JSON line.
+ * @property {number} [processId] - Process identity, defaults to process.pid.
+ * @property {() => Date} [now] - Clock provider.
+ * @property {{write(chunk: string): unknown}} [stderr] - Failure report destination.
+ * @typedef {object} JsonlFileLoggerOptions
+ * @property {string} directory - Persistent log directory.
+ * @property {string} role - Stable process/component role used in the filename.
+ * @property {number} [processId] - Process identity, defaults to process.pid.
+ * @property {number} [maxFileBytes] - Maximum bytes per active or rotated file.
+ * @property {number} [maxFiles] - Total retained files including the active file.
+ * @property {() => Date} [now] - Clock provider.
+ * @property {{write(chunk: string): unknown}} [stderr] - Failure report destination.
+ */
+
+/**
+ * Creates an allowlisted structured logger around a caller-provided line writer.
+ * Writer errors are isolated and reported at most once.
+ * @param {StructuredLoggerOptions} options - Logger identity and writer.
+ * @returns {DiagnosticLogger} Best-effort logger.
+ */
+export function createStructuredLogger(options) {
+  return createStructuredLoggerWithFailureCode(options, "LOGGER_WRITER_ERROR")
+}
+
+/**
+ * @param {StructuredLoggerOptions} options - Logger identity and writer.
+ * @param {'LOGGER_IO_ERROR' | 'LOGGER_WRITER_ERROR'} failureCode - Fixed failure classification.
+ * @returns {DiagnosticLogger} Best-effort logger.
+ */
+function createStructuredLoggerWithFailureCode(options, failureCode) {
+  validateRole(options?.role)
+  const role = options.role
+  const writeLine = options.writeLine
+  if (typeof writeLine !== "function") throw new TypeError("writeLine must be a function")
+  const processId = validateProcessId(options.processId ?? process.pid)
+  const now = options.now ?? (() => new Date())
+  if (typeof now !== "function") throw new TypeError("now must be a function")
+  const stderr = options.stderr ?? process.stderr
+  let reported = false
+  const reportOnce = () => {
+    if (reported) return
+    reported = true
+    reportFailure(stderr, failureCode)
+  }
+
+  return {
+    log(event, fields = {}) {
+      try {
+        const safeFields = sanitizeFields(event, fields)
+        if (safeFields === undefined) return
+        const timestamp = now()
+        if (!(timestamp instanceof Date) || !Number.isFinite(timestamp.getTime())) throw new TypeError("Logger clock returned an invalid date")
+        const base = {timestamp: timestamp.toISOString(), event, processId, role}
+        let line = formatLogLine(base, safeFields)
+        if (Buffer.byteLength(line) > MAX_JSONL_BYTES && safeFields.errorCode !== undefined) {
+          /** @type {Record<string, string | number | boolean>} */
+          const boundedFields = {...safeFields}
+          delete boundedFields.errorStack
+          if (typeof boundedFields.errorMessage === "string") {
+            const emptyMessageLine = formatLogLine(base, {...boundedFields, errorMessage: ""})
+            const availableBytes = Math.max(0, MAX_JSONL_BYTES - Buffer.byteLength(emptyMessageLine))
+            boundedFields.errorMessage = truncateDiagnosticText(boundedFields.errorMessage, availableBytes)
+          }
+          line = formatLogLine(base, boundedFields)
+          if (Buffer.byteLength(line) > MAX_JSONL_BYTES) {
+            delete boundedFields.errorMessage
+            line = formatLogLine(base, boundedFields)
+          }
+          if (Buffer.byteLength(line) > MAX_JSONL_BYTES) {
+            delete boundedFields.errorName
+            line = formatLogLine(base, boundedFields)
+          }
+        }
+        if (Buffer.byteLength(line) > MAX_JSONL_BYTES) line = formatLogLine(base, {})
+        observeRejection(writeLine(line), reportOnce)
+      } catch {
+        reportOnce()
+      }
+    }
+  }
+}
+
+/**
+ * Creates a synchronous append-only JSONL logger with numbered rotation.
+ * Each call opens and closes the file, avoiding descriptor lifecycle coupling.
+ * @param {JsonlFileLoggerOptions} options - File sink options.
+ * @returns {DiagnosticLogger} Best-effort file logger.
+ */
+export function createJsonlFileLogger(options) {
+  if (typeof options?.directory !== "string" || options.directory.trim().length === 0) throw new TypeError("directory must be a non-empty string")
+  validateRole(options.role)
+  const directory = options.directory
+  const role = options.role
+  const processId = validateProcessId(options.processId ?? process.pid)
+  const maxFileBytes = validateMaxFileBytes(options.maxFileBytes ?? DEFAULT_LOG_MAX_FILE_BYTES)
+  const maxFiles = validateMaxFiles(options.maxFiles ?? DEFAULT_LOG_MAX_FILES)
+  const fileName = `${role}-${processId}.jsonl`
+  const activePath = join(directory, fileName)
+  let familyPruned = false
+
+  return createStructuredLoggerWithFailureCode({
+    role,
+    processId,
+    ...(options.now === undefined ? {} : {now: options.now}),
+    ...(options.stderr === undefined ? {} : {stderr: options.stderr}),
+    writeLine(line) {
+      const bytes = Buffer.byteLength(line)
+      if (bytes > maxFileBytes) throw new Error("Bounded JSON line exceeds configured file size")
+      mkdirSync(directory, {recursive: true, mode: 0o700})
+      const directoryStats = lstatSync(directory)
+      if (!directoryStats.isDirectory() || (directoryStats.mode & 0o777) !== 0o700) throw new Error("Unsafe log directory")
+      let active = inspectLogPath(activePath)
+      if (active?.incomplete && (maxFiles === 1 || active.size > maxFileBytes)) throw new Error("Cannot retain incomplete log within configured bounds")
+      if (!familyPruned) {
+        pruneObsoleteRoleFiles(directory, role, processId, maxFiles)
+        pruneFileFamily(directory, fileName, maxFileBytes, maxFiles)
+        familyPruned = true
+        active = inspectLogPath(activePath)
+      }
+      if (active !== undefined && (active.incomplete || active.size + bytes > maxFileBytes)) {
+        if (active.incomplete && (maxFiles === 1 || active.size > maxFileBytes)) throw new Error("Cannot retain incomplete log within configured bounds")
+        rotate(activePath, maxFiles)
+      }
+      const descriptor = openSync(activePath, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600)
+      try {
+        const current = inspectLogDescriptor(descriptor)
+        if (current.incomplete || current.size + bytes > maxFileBytes) throw new Error("Active log is not safe to append")
+        appendFileSync(descriptor, line, {encoding: "utf8"})
+      } finally {
+        closeSync(descriptor)
+      }
+    }
+  }, "LOGGER_IO_ERROR")
+}
+
+/**
+ * @param {string} path - Active log path.
+ * @returns {{size: number, incomplete: boolean} | undefined} Bounded tail state, or an absent path.
+ */
+function inspectLogPath(path) {
+  let descriptor
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  } catch (error) {
+    if (isMissing(error)) return undefined
+    throw error
+  }
+  try {
+    return inspectLogDescriptor(descriptor)
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/**
+ * @param {number} descriptor - Open log descriptor.
+ * @returns {{size: number, incomplete: boolean}} Size and final-byte framing state.
+ */
+function inspectLogDescriptor(descriptor) {
+  const stats = fstatSync(descriptor)
+  if (!stats.isFile() || (stats.mode & 0o777) !== 0o600) throw new Error("Unsafe log file")
+  if (stats.size === 0) return {size: 0, incomplete: false}
+  const tail = Buffer.alloc(1)
+  if (readSync(descriptor, tail, 0, 1, stats.size - 1) !== 1) throw new Error("Could not inspect log tail")
+  return {size: stats.size, incomplete: tail[0] !== 10}
+}
+
+/**
+ * Retains at most maxFiles logs across process instances that are definitely
+ * exited. Live and indeterminate process families are never cleanup targets.
+ * @param {string} directory - Configured log directory.
+ * @param {string} role - Validated logger role.
+ * @param {number} currentProcessId - This logger's configured process ID.
+ * @param {number} maxFiles - Obsolete same-role file retention bound.
+ * @returns {void}
+ */
+function pruneObsoleteRoleFiles(directory, role, currentProcessId, maxFiles) {
+  /** @type {Map<number, boolean>} */
+  const exitedProcesses = new Map()
+  /** @type {Array<{entry: string, path: string, processId: number, modifiedAt: number, device: number, inode: number, size: number, changedAt: number}>} */
+  const candidates = []
+  for (const entry of readdirSync(directory)) {
+    const processId = roleLogProcessId(entry, role)
+    if (processId === undefined || processId === currentProcessId) continue
+    let exited = exitedProcesses.get(processId)
+    if (exited === undefined) {
+      exited = processDefinitelyExited(processId)
+      exitedProcesses.set(processId, exited)
+    }
+    if (!exited) continue
+    const path = join(directory, entry)
+    let stats
+    try {
+      stats = lstatSync(path)
+    } catch (error) {
+      if (isMissing(error)) continue
+      throw error
+    }
+    if (!stats.isFile()) continue
+    candidates.push({
+      entry,
+      path,
+      processId,
+      modifiedAt: Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : 0,
+      device: stats.dev,
+      inode: stats.ino,
+      size: stats.size,
+      changedAt: stats.ctimeMs
+    })
+  }
+  candidates.sort((left, right) => {
+    if (left.modifiedAt !== right.modifiedAt) return right.modifiedAt - left.modifiedAt
+    if (left.entry < right.entry) return -1
+    if (left.entry > right.entry) return 1
+    return 0
+  })
+  for (const candidate of candidates.slice(maxFiles)) {
+    // Re-probe around an unchanged-file check. If the PID was reused or the
+    // family changed while cleanup was pending, preserve it for a later scan.
+    if (!processDefinitelyExited(candidate.processId) || !sameFile(candidate) || !processDefinitelyExited(candidate.processId)) continue
+    unlinkIfPresent(candidate.path)
+  }
+}
+
+/**
+ * @param {string} entry - Directory entry.
+ * @param {string} role - Validated role prefix.
+ * @returns {number | undefined} Parsed owner PID for a recognized log file.
+ */
+function roleLogProcessId(entry, role) {
+  const prefix = `${role}-`
+  if (!entry.startsWith(prefix)) return undefined
+  const match = /^(0|[1-9][0-9]*)\.jsonl(?:\.[1-9][0-9]*)?$/.exec(entry.slice(prefix.length))
+  if (match === null) return undefined
+  const processId = Number(match[1])
+  return Number.isSafeInteger(processId) && processId > 0 ? processId : undefined
+}
+
+/**
+ * @param {{path: string, device: number, inode: number, size: number, changedAt: number}} candidate - Original file snapshot.
+ * @returns {boolean} Whether the candidate is still the same regular file.
+ */
+function sameFile(candidate) {
+  try {
+    const stats = lstatSync(candidate.path)
+    return stats.isFile() && stats.dev === candidate.device && stats.ino === candidate.inode && stats.size === candidate.size && stats.ctimeMs === candidate.changedAt
+  } catch (error) {
+    if (isMissing(error)) return false
+    throw error
+  }
+}
+
+/**
+ * Treats only ESRCH as proof that a PID is unused. PID reuse, permission
+ * failures, unsupported probes, and malformed errors all retain the family.
+ * @param {number} processId - Candidate owner PID.
+ * @returns {boolean} Whether the process is definitely exited.
+ */
+function processDefinitelyExited(processId) {
+  try {
+    process.kill(processId, 0)
+    return false
+  } catch (error) {
+    try {
+      return error !== null && typeof error === "object" && /** @type {{code?: unknown}} */ (error).code === "ESRCH"
+    } catch {
+      return false
+    }
+  }
+}
+
+/**
+ * Removes only this process/role family's files that violate current bounds.
+ * @param {string} directory - Configured log directory.
+ * @param {string} fileName - Active file basename.
+ * @param {number} maxFileBytes - Per-file byte bound.
+ * @param {number} maxFiles - Total family retention bound.
+ * @returns {void}
+ */
+function pruneFileFamily(directory, fileName, maxFileBytes, maxFiles) {
+  const rotatedPrefix = `${fileName}.`
+  for (const entry of readdirSync(directory)) {
+    let index
+    if (entry === fileName) {
+      index = 0
+    } else if (entry.startsWith(rotatedPrefix) && /^[1-9][0-9]*$/.test(entry.slice(rotatedPrefix.length))) {
+      index = Number(entry.slice(rotatedPrefix.length))
+    } else {
+      continue
+    }
+    const path = join(directory, entry)
+    if (!Number.isSafeInteger(index) || index >= maxFiles || statSync(path).size > maxFileBytes) unlinkSync(path)
+  }
+}
+
+/**
+ * Sends an allowlisted event to an optional embedded logger without allowing a
+ * logger exception to alter transport behavior.
+ * @param {DiagnosticLogger | undefined} logger - Optional consumer logger.
+ * @param {string} event - Allowlisted event name.
+ * @param {Record<string, unknown>} [fields] - Candidate diagnostic fields.
+ * @returns {void}
+ */
+export function logDiagnostic(logger, event, fields = {}) {
+  try {
+    if (logger === undefined || logger === null || typeof logger.log !== "function") return
+    const safeFields = sanitizeFields(event, fields)
+    if (safeFields !== undefined) {
+      const result = /** @type {(event: string, fields: Record<string, unknown>) => unknown} */ (logger.log)(event, safeFields)
+      observeRejection(result, () => reportLoggerFailure(logger))
+    }
+  } catch {
+    reportLoggerFailure(logger)
+  }
+}
+
+/**
+ * Returns error fields for operational diagnostics.
+ * @param {unknown} error - Failure value.
+ * @param {string} [fallback] - Known fallback code.
+ * @returns {{errorCode: string, errorClass: string, errorMessage?: string, errorName?: string, errorStack?: string}} Error classification and details.
+ */
+export function errorDiagnostics(error, fallback = "UNKNOWN") {
+  let code
+  let errorMessage
+  let errorName
+  let errorStack
+  try {
+    if (error instanceof Error) {
+      code = /** @type {{code?: unknown}} */ (error).code
+      errorMessage = error.message
+      errorName = error.name
+      errorStack = error.stack
+    } else if (typeof error === "string") {
+      errorMessage = error
+    } else if (error !== null && typeof error === "object") {
+      code = /** @type {{code?: unknown}} */ (error).code
+    }
+  } catch {
+    code = undefined
+  }
+  const errorCode = normalizeErrorCode(typeof code === "string" ? code : fallback)
+  const diagnostics = {
+    errorCode,
+    errorClass: classifyError(errorCode)
+  }
+  Object.defineProperty(diagnostics, ERROR_DETAILS, {
+    enumerable: true,
+    value: {
+      ...(errorName === undefined ? {} : {errorName: truncateDiagnosticText(redactCredentialText(errorName), MAX_ERROR_NAME_BYTES)}),
+      ...(errorMessage === undefined ? {} : {errorMessage: truncateDiagnosticText(redactCredentialText(errorMessage), MAX_ERROR_MESSAGE_BYTES)}),
+      ...(errorStack === undefined ? {} : {errorStack: truncateDiagnosticText(redactCredentialText(errorStack), MAX_ERROR_STACK_BYTES)})
+    }
+  })
+  return diagnostics
+}
+
+/**
+ * @param {string} event - Event name.
+ * @param {Record<string, unknown>} fields - Candidate fields.
+ * @returns {Record<string, string | number | boolean> | undefined} Allowlisted fields, or undefined for an unknown event.
+ */
+function sanitizeFields(event, fields) {
+  const allowed = EVENT_FIELDS.get(event)
+  if (allowed === undefined || typeof fields !== "object" || fields === null || Array.isArray(fields)) return undefined
+  /** @type {Record<string, string | number | boolean>} */
+  const safe = {}
+  for (const field of allowed) {
+    const value = fields[field]
+    if (NUMBER_FIELDS.has(field)) {
+      if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) safe[field] = value
+      continue
+    }
+    if (field === "gatewayId") {
+      if (typeof value === "string") {
+        const bounded = value.slice(0, MAX_GATEWAY_ID_BYTES)
+        if (GATEWAY_ID.test(bounded)) safe.gatewayId = bounded
+      }
+      continue
+    }
+    if (field === "runtimeMode" && typeof value === "string" && RUNTIME_MODES.has(value)) safe.runtimeMode = value
+    else if (field === "transportSecurity" && typeof value === "string" && TRANSPORT_SECURITY.has(value)) safe.transportSecurity = value
+    else if (field === "compression" && typeof value === "string" && COMPRESSION.has(value)) safe.compression = value
+    else if ((field === "state" || field === "physicalState") && typeof value === "string" && STATES.has(value)) safe[field] = value
+    else if ((field === "reconnect" || field === "recovered") && typeof value === "boolean") safe[field] = value
+    else if (field === "errorCode" && value !== undefined) {
+      const errorCode = normalizeErrorCode(value)
+      safe.errorCode = errorCode
+      safe.errorClass = classifyError(errorCode)
+    }
+  }
+  const errorDetails = Object.getOwnPropertyDescriptor(fields, ERROR_DETAILS)?.value
+  if (allowed.has("errorCode") && errorDetails !== null && typeof errorDetails === "object" && !Array.isArray(errorDetails)) {
+    const typedErrorDetails = /** @type {{errorMessage?: unknown, errorName?: unknown, errorStack?: unknown}} */ (errorDetails)
+    if (typeof typedErrorDetails.errorName === "string") safe.errorName = typedErrorDetails.errorName
+    if (typeof typedErrorDetails.errorMessage === "string") safe.errorMessage = typedErrorDetails.errorMessage
+    if (typeof typedErrorDetails.errorStack === "string") safe.errorStack = typedErrorDetails.errorStack
+    Object.defineProperty(safe, ERROR_DETAILS, {enumerable: true, value: errorDetails})
+  }
+  return safe
+}
+
+/**
+ * @param {{event: string, processId: number, role: string, timestamp: string}} base - Required JSONL fields.
+ * @param {Record<string, string | number | boolean>} fields - Sanitized event fields.
+ * @returns {string} One JSONL record.
+ */
+function formatLogLine(base, fields) {
+  return `${JSON.stringify({...base, ...fields})}\n`
+}
+
+/**
+ * @param {string} value - Diagnostic value.
+ * @param {number} maxBytes - Maximum UTF-8 byte length.
+ * @returns {string} Bounded diagnostic value.
+ */
+function truncateDiagnosticText(value, maxBytes) {
+  let truncated = ""
+  let bytes = 0
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character)
+    if (bytes + characterBytes > maxBytes) break
+    truncated += character
+    bytes += characterBytes
+  }
+  return truncated
+}
+
+/**
+ * @param {string} value - Error text.
+ * @returns {string} Error text without credential-shaped values.
+ */
+function redactCredentialText(value) {
+  return value
+    .replace(/(Bearer\s+)[^\s,;]+/giu, "$1[REDACTED]")
+    .replace(/(\/\/)[^\s/@]+@/gu, "$1[REDACTED]@")
+    .replace(/((?:password|token|authorization)\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/giu, "$1[REDACTED]")
+}
+
+/**
+ * @param {unknown} value - Candidate error code.
+ * @returns {string} Allowlisted error code.
+ */
+function normalizeErrorCode(value) {
+  if (typeof value !== "string") return "UNKNOWN"
+  if (SAFE_ERROR_CODES.has(value)) return value
+  if (value.startsWith("ERR_TLS_") || value.startsWith("ERR_SSL_") || value.includes("CERT") || value.includes("VERIFY") || value.includes("SELF_SIGNED") || value.includes("ISSUER")) return "TLS_ERROR"
+  return "UNKNOWN"
+}
+
+/**
+ * @param {string} code - Sanitized error code.
+ * @returns {string} Bounded error class.
+ */
+function classifyError(code) {
+  if (code === "UNKNOWN") return "unknown"
+  if (code === "TLS_ERROR") return "tls"
+  if (code === "SOCKETDUCT_AUTH_TIMEOUT" || code === "HANDSHAKE_TIMEOUT" || code === "TARGET_OPEN_TIMEOUT" || code === "ETIMEDOUT") return "timeout"
+  if (code.startsWith("AUTH_") || code.includes("NEGOTIATION")) return "authentication"
+  if (code.startsWith("SOCKETDUCT_SET_") || code.includes("BUFFER_LIMIT") || code.includes("STREAM_LIMIT") || code === "INPUT_LIMIT_EXCEEDED") return "limit"
+  if (code.startsWith("E") || code.includes("DISCONNECTED") || code.includes("UNAVAILABLE") || code === "TRANSPORT_CLOSED") return "network"
+  if (code.includes("PROTOCOL") || code.includes("GENERATION")) return "protocol"
+  return "lifecycle"
+}
+
+/**
+ * @param {string} activePath - Active JSONL path.
+ * @param {number} maxFiles - Total retained files.
+ * @returns {void}
+ */
+function rotate(activePath, maxFiles) {
+  if (maxFiles === 1) {
+    unlinkIfPresent(activePath)
+    return
+  }
+  unlinkIfPresent(`${activePath}.${maxFiles - 1}`)
+  for (let index = maxFiles - 2; index >= 1; index -= 1) renameIfPresent(`${activePath}.${index}`, `${activePath}.${index + 1}`)
+  renameSync(activePath, `${activePath}.1`)
+}
+
+/**
+ * @param {string} source - Existing path.
+ * @param {string} destination - Rotated path.
+ * @returns {void}
+ */
+function renameIfPresent(source, destination) {
+  try {
+    renameSync(source, destination)
+  } catch (error) {
+    if (!isMissing(error)) throw error
+  }
+}
+
+/**
+ * @param {string} path - Path to remove if present.
+ * @returns {void}
+ */
+function unlinkIfPresent(path) {
+  try {
+    unlinkSync(path)
+  } catch (error) {
+    if (!isMissing(error)) throw error
+  }
+}
+
+/**
+ * @param {unknown} error - Filesystem error.
+ * @returns {boolean} Whether the error represents a missing path.
+ */
+function isMissing(error) {
+  return error !== null && typeof error === "object" && /** @type {{code?: unknown}} */ (error).code === "ENOENT"
+}
+
+/**
+ * @param {{write(chunk: string): unknown}} stderr - Failure destination.
+ * @param {string} code - Bounded code.
+ * @returns {void}
+ */
+function reportFailure(stderr, code) {
+  try {
+    stderr.write(`Socketduct logger failure (${code})\n`)
+  } catch {
+    // Logging must never recursively report its own failure.
+  }
+}
+
+/**
+ * Attaches a rejection handler when a custom writer returns a promise.
+ * @param {unknown} result - Writer result.
+ * @param {() => void} onRejected - Bounded failure reporter.
+ * @returns {void}
+ */
+function observeRejection(result, onRejected) {
+  if (result === null || (typeof result !== "object" && typeof result !== "function")) return
+  Promise.resolve(result).catch(onRejected)
+}
+
+/**
+ * Reports one failure for a caller-provided logger object.
+ * @param {DiagnosticLogger | undefined} logger - Failed logger.
+ * @returns {void}
+ */
+function reportLoggerFailure(logger) {
+  if (logger === undefined || logger === null || typeof logger !== "object" || FAILED_LOGGERS.has(logger)) return
+  FAILED_LOGGERS.add(logger)
+  reportFailure(process.stderr, "LOGGER_WRITER_ERROR")
+}
+
+/**
+ * @param {string} role - Candidate role.
+ * @returns {void}
+ */
+function validateRole(role) {
+  if (typeof role !== "string" || !ROLE.test(role)) throw new TypeError("role must be 1-64 lowercase letters, digits, or hyphens")
+}
+
+/**
+ * @param {number} processId - Candidate process ID.
+ * @returns {number} Validated process ID.
+ */
+function validateProcessId(processId) {
+  if (!Number.isSafeInteger(processId) || processId < 0) throw new RangeError("processId must be a non-negative safe integer")
+  return processId
+}
+
+/**
+ * @param {number} value - Candidate file byte bound.
+ * @returns {number} Validated byte bound.
+ */
+export function validateMaxFileBytes(value) {
+  if (!Number.isSafeInteger(value) || value < MIN_LOG_MAX_FILE_BYTES) throw new RangeError(`maxFileBytes must be an integer of at least ${MIN_LOG_MAX_FILE_BYTES}`)
+  return value
+}
+
+/**
+ * @param {number} value - Candidate retention bound.
+ * @returns {number} Validated retention bound.
+ */
+export function validateMaxFiles(value) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > MAX_LOG_FILES) throw new RangeError(`maxFiles must be an integer from 1 to ${MAX_LOG_FILES}`)
+  return value
+}