socketduct 0.1.18 → 0.1.20

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

@@ -0,0 +1,538 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns, jsdoc/require-returns-description */
+import {randomBytes} from "node:crypto"
+import {Worker} from "node:worker_threads"
+
+import {formatDiagnosticLogLine} from "./structured-logger.js"
+import {createLogBatchId} from "./log-batch.js"
+import {DEFAULT_LOG_COMPRESSION_LEVEL} from "./zstd-frame-codec.js"
+
+export {DEFAULT_LOG_COMPRESSION_LEVEL} from "./zstd-frame-codec.js"
+
+export const DEFAULT_LOG_FRAME_BYTES = 1024 * 1024
+export const DEFAULT_LOG_FLUSH_INTERVAL_MS = 1000
+export const DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS = 250
+export const DEFAULT_LOG_SEGMENT_BYTES = 128 * 1024 * 1024
+export const DEFAULT_LOG_QUEUE_BYTES = 64 * 1024 * 1024
+export const DEFAULT_LOG_CRITICAL_RESERVE_BYTES = 8 * 1024 * 1024
+export const DEFAULT_LOG_RETENTION_DAYS = 30
+export const DEFAULT_LOG_RETENTION_BYTES = 4 * 1024 * 1024 * 1024
+
+const ROLE = /^[a-z][a-z0-9-]{0,63}$/
+const REPLACEABLE_EVENTS = new Set(["runtime.status", "transport_set.member_state"])
+const NONCRITICAL_EVENTS = new Set(["runtime.status", "transport.connecting", "transport.connected", "transport.reconnect_scheduled", "transport.reconnect_succeeded", "transport_set.member_state"])
+
+/** @typedef {{event: string, key: string, sequence: bigint, buffer: Buffer, charge: number, internal: boolean}} PendingRecord */
+/** @typedef {{writerEpoch: string, acceptedHighWater: string, durableHighWater: string, queuedBytes: number, inFlightBytes: number, allocatedBytes: number, workerRestarts: number, workerState: string, health: string, state: string, criticalDrops: number, noncriticalDrops: number, coalesced: number}} LoggerStatus */
+
+/**
+ * @typedef {object} CompressedJsonlFileLoggerOptions
+ * @property {string} directory - Private compressed-log directory.
+ * @property {string} role - Stable component role.
+ * @property {number} [processId] - Process identity for the JSON envelope.
+ * @property {() => Date} [now] - Clock provider.
+ * @property {number} [frameMaxBytes] - Maximum uncompressed JSONL frame batch.
+ * @property {number} [flushIntervalMs] - Ordinary maximum batch latency.
+ * @property {number} [criticalFlushIntervalMs] - Critical maximum batch latency.
+ * @property {number} [maxSegmentBytes] - Maximum compressed segment size.
+ * @property {number} [maxQueueBytes] - Shared producer/worker allocation bound.
+ * @property {number} [criticalReserveBytes] - Queue bytes reserved for critical events.
+ * @property {number} [compressionLevel] - Explicit zstd level, default 19.
+ * @property {number} [retentionDays] - Closed-segment maximum age, default 30 days.
+ * @property {number} [retentionBytes] - Directory quota, default 4 GiB.
+ * @property {{write(chunk: string): unknown}} [stderr] - Secret-free health reporting destination.
+ */
+
+/** Bounded asynchronous producer for durable, independently indexed zstd frames. */
+export class CompressedJsonlFileLogger {
+  /** @type {CompressedJsonlFileLoggerOptions} */ #options
+  /** @type {Buffer} */ #writerEpoch = randomBytes(16)
+  /** @type {string} */ #writerEpochText
+  /** @type {bigint} */ #acceptedHighWater = 0n
+  /** @type {bigint} */ #durableHighWater = 0n
+  /** @type {PendingRecord[]} */ #pending = []
+  /** @type {{batchId: string, firstSequence: bigint, lastSequence: bigint, jsonl: Buffer, charge: number, lifecycleSource: boolean} | undefined} */ #inFlight
+  /** @type {number} */ #pendingBytes = 0
+  /** @type {number} */ #pendingRawBytes = 0
+  /** @type {number} */ #inFlightBytes = 0
+  /** @type {number} */ #criticalDrops = 0
+  /** @type {number} */ #noncriticalDrops = 0
+  /** @type {number} */ #coalesced = 0
+  /** @type {Worker | undefined} */ #worker
+  /** @type {boolean} */ #workerReady = false
+  /** @type {number} */ #workerGeneration = 0
+  /** @type {number[]} */ #workerRestarts = []
+  /** @type {'starting' | 'healthy' | 'degraded' | 'failed' | 'closing' | 'closed'} */ #state = "starting"
+  /** @type {ReturnType<typeof setTimeout> | undefined} */ #flushTimer
+  /** @type {number | undefined} */ #flushTimerDueAt
+  /** @type {boolean} */ #accepting = true
+  /** @type {Array<{barrier: bigint, resolve: () => void, reject: (error: Error) => void}>} */ #flushWaiters = []
+  /** @type {Error | undefined} */ #failure
+  /** @type {Promise<LoggerStatus> | undefined} */ #closePromise
+  /** @type {(() => void) | undefined} */ #resolveWorkerClosed
+  /** @type {((error: Error) => void) | undefined} */ #rejectWorkerClosed
+  /** @type {boolean} */ #failureReported = false
+
+  /** @param {CompressedJsonlFileLoggerOptions} options - Storage and resource policy. */
+  constructor(options) {
+    validateOptions(options)
+    this.#options = options
+    this.#writerEpochText = this.#writerEpoch.toString("base64url")
+    this.#spawnWorker(false)
+  }
+
+  /**
+   * Sanitizes and queues one record without blocking the caller.
+   * @param event
+   * @param fields
+   * @returns {'accepted' | 'coalesced' | 'dropped'} Queue outcome.
+   */
+  log(/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) {
+    const critical = !NONCRITICAL_EVENTS.has(event)
+    if (!this.#accepting || this.#state === "closed" || (this.#state === "failed" && !critical)) {
+      this.#recordDrop(critical)
+      return "dropped"
+    }
+    const sequence = this.#acceptedHighWater + 1n
+    let line
+    try {
+      line = formatDiagnosticLogLine({
+        role: this.#options.role,
+        ...(this.#options.processId === undefined ? {} : {processId: this.#options.processId}),
+        ...(this.#options.now === undefined ? {} : {now: this.#options.now}),
+        event,
+        fields,
+        envelope: {writerEpoch: this.#writerEpochText, eventSequence: sequence.toString()}
+      })
+    } catch {
+      this.#recordDrop(critical)
+      return "dropped"
+    }
+    if (line === undefined) {
+      this.#recordDrop(critical)
+      return "dropped"
+    }
+    const buffer = Buffer.from(line)
+    const charge = conservativeCharge(buffer.length)
+    const maxQueueBytes = this.#options.maxQueueBytes ?? DEFAULT_LOG_QUEUE_BYTES
+    const normalLimit = maxQueueBytes - (this.#options.criticalReserveBytes ?? DEFAULT_LOG_CRITICAL_RESERVE_BYTES)
+    const limit = critical ? maxQueueBytes : normalLimit
+    const allocated = this.#pendingBytes + this.#inFlightBytes
+    const key = coalesceKey(event, fields)
+    if (allocated + charge > limit && REPLACEABLE_EVENTS.has(event)) {
+      const existing = this.#pending.findLast((record) => record.key === key)
+      if (existing !== undefined) {
+        const replacementLine = formatDiagnosticLogLine({
+          role: this.#options.role,
+          ...(this.#options.processId === undefined ? {} : {processId: this.#options.processId}),
+          ...(this.#options.now === undefined ? {} : {now: this.#options.now}),
+          event,
+          fields,
+          envelope: {writerEpoch: this.#writerEpochText, eventSequence: existing.sequence.toString()}
+        })
+        if (replacementLine !== undefined) {
+          const replacement = Buffer.from(replacementLine)
+          const replacementCharge = conservativeCharge(replacement.length)
+          if (allocated - existing.charge + replacementCharge <= limit) {
+            this.#pendingBytes += replacementCharge - existing.charge
+            this.#pendingRawBytes += replacement.length - existing.buffer.length
+            existing.buffer = replacement
+            existing.charge = replacementCharge
+            this.#coalesced += 1
+            return "coalesced"
+          }
+        }
+      }
+    }
+    if (allocated + charge > limit || buffer.length > (this.#options.frameMaxBytes ?? DEFAULT_LOG_FRAME_BYTES)) {
+      this.#recordDrop(critical)
+      return "dropped"
+    }
+    this.#acceptedHighWater = sequence
+    this.#pending.push({event, key, sequence, buffer, charge, internal: false})
+    this.#pendingBytes += charge
+    this.#pendingRawBytes += buffer.length
+    this.#worker?.ref()
+    if (this.#state !== "failed") {
+      if (this.#pendingRawBytes >= (this.#options.frameMaxBytes ?? DEFAULT_LOG_FRAME_BYTES)) {
+        this.#clearFlushTimer()
+        this.#sendNext()
+      } else this.#scheduleFlush(critical)
+    }
+    return "accepted"
+  }
+
+  /** Resolves only after every accepted record through the call is data+index synced. */
+  /** @returns {Promise<void>} */
+  flush() {
+    if (this.#failure !== undefined) return Promise.reject(this.#failure)
+    const barrier = this.#acceptedHighWater
+    this.#clearFlushTimer()
+    this.#sendNext()
+    return new Promise((resolve, reject) => {
+      this.#flushWaiters.push({barrier, resolve, reject})
+      this.#settleFlushWaiters()
+    })
+  }
+
+  /** Stops acceptance, flushes, seals, and terminates the worker exactly once. */
+  /** @returns {Promise<LoggerStatus>} */
+  close() {
+    if (this.#closePromise !== undefined) return this.#closePromise
+    this.#accepting = false
+    this.#state = this.#failure === undefined ? "closing" : "failed"
+    this.#closePromise = this.#closeInternal()
+    return this.#closePromise
+  }
+
+  /** @returns {LoggerStatus} */
+  status() {
+    return {
+      writerEpoch: this.#writerEpochText,
+      acceptedHighWater: this.#acceptedHighWater.toString(),
+      durableHighWater: this.#durableHighWater.toString(),
+      queuedBytes: this.#pendingBytes,
+      inFlightBytes: this.#inFlightBytes,
+      allocatedBytes: this.#pendingBytes + this.#inFlightBytes,
+      workerRestarts: this.#workerRestarts.length,
+      workerState: this.#workerReady ? "ready" : this.#state === "failed" ? "failed" : "starting",
+      health: this.#state === "failed" ? "failed" : this.#state === "degraded" ? "degraded" : "healthy",
+      state: this.#state,
+      criticalDrops: this.#criticalDrops,
+      noncriticalDrops: this.#noncriticalDrops,
+      coalesced: this.#coalesced
+    }
+  }
+
+  /** @returns {Promise<LoggerStatus>} */
+  async #closeInternal() {
+    try {
+      await this.flush()
+      while (this.#durableHighWater < this.#acceptedHighWater || this.#pending.length > 0 || this.#inFlight !== undefined) await this.flush()
+      this.#enqueueInternal("log_closed", {criticalDrops: this.#criticalDrops, noncriticalDrops: this.#noncriticalDrops, coalescedDrops: this.#coalesced})
+      await this.flush()
+      const worker = this.#worker
+      if (worker !== undefined) {
+        /** @type {Promise<void>} */
+        const closed = new Promise((resolve, reject) => { this.#resolveWorkerClosed = resolve; this.#rejectWorkerClosed = reject })
+        worker.ref()
+        worker.postMessage({type: "close"})
+        await closed
+      }
+      this.#state = "closed"
+      return this.status()
+    } catch (error) {
+      this.#state = "failed"
+      throw error
+    } finally {
+      this.#clearFlushTimer()
+    }
+  }
+
+  /** @param {boolean} critical - Whether the oldest pending event is critical. */
+  #scheduleFlush(critical) {
+    const delay = critical ? this.#options.criticalFlushIntervalMs ?? DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS : this.#options.flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS
+    const dueAt = Date.now() + delay
+    if (this.#flushTimer !== undefined) {
+      if (this.#flushTimerDueAt !== undefined && this.#flushTimerDueAt <= dueAt) return
+      clearTimeout(this.#flushTimer)
+    }
+    this.#flushTimerDueAt = dueAt
+    this.#flushTimer = setTimeout(() => {
+      this.#flushTimer = undefined
+      this.#flushTimerDueAt = undefined
+      this.#sendNext()
+    }, Math.max(0, dueAt - Date.now()))
+  }
+
+  #clearFlushTimer() {
+    if (this.#flushTimer !== undefined) clearTimeout(this.#flushTimer)
+    this.#flushTimer = undefined
+    this.#flushTimerDueAt = undefined
+  }
+
+  #sendNext() {
+    if (!this.#workerReady || this.#worker === undefined || this.#inFlight !== undefined || this.#pending.length === 0) {
+      if (this.#pending.length === 0 && this.#inFlight === undefined && this.#flushWaiters.length === 0) this.#worker?.unref()
+      return
+    }
+    const maxBytes = this.#options.frameMaxBytes ?? DEFAULT_LOG_FRAME_BYTES
+    /** @type {PendingRecord[]} */
+    const selected = []
+    let rawBytes = 0
+    while (this.#pending.length > 0) {
+      const next = /** @type {PendingRecord} */ (this.#pending[0])
+      if (selected.length > 0 && rawBytes + next.buffer.length > maxBytes) break
+      selected.push(/** @type {PendingRecord} */ (this.#pending.shift()))
+      rawBytes += next.buffer.length
+    }
+    const jsonl = Buffer.concat(selected.map((record) => record.buffer), rawBytes)
+    const firstSequence = /** @type {PendingRecord} */ (selected[0]).sequence
+    const lastSequence = /** @type {PendingRecord} */ (selected.at(-1)).sequence
+    const charge = selected.reduce((total, record) => total + record.charge, 0)
+    const lifecycleSource = selected.some((record) => !record.internal)
+    this.#pendingBytes -= charge
+    this.#pendingRawBytes -= rawBytes
+    this.#inFlightBytes = charge
+    this.#inFlight = {
+      batchId: createLogBatchId(this.#writerEpoch, firstSequence, lastSequence, jsonl).toString("base64url"),
+      firstSequence,
+      lastSequence,
+      jsonl,
+      charge,
+      lifecycleSource
+    }
+    if (lifecycleSource) this.#enqueueInternal("log_batch_accepted", {queuedBytes: this.#pendingBytes + this.#inFlightBytes})
+    this.#postInFlight()
+  }
+
+  #postInFlight() {
+    const batch = this.#inFlight
+    if (batch === undefined || this.#worker === undefined || !this.#workerReady) return
+    this.#worker.postMessage({
+      type: "batch",
+      batchId: batch.batchId,
+      firstSequence: batch.firstSequence.toString(),
+      lastSequence: batch.lastSequence.toString(),
+      jsonl: batch.jsonl
+    })
+  }
+
+  /** @param {boolean} restart - Whether this worker replaces a failed generation. */
+  #spawnWorker(restart) {
+    const generation = ++this.#workerGeneration
+    this.#workerReady = false
+    const worker = new Worker(new URL("./compressed-log-worker.js", import.meta.url), {
+      workerData: {
+        directory: this.#options.directory,
+        role: this.#options.role,
+        writerEpoch: this.#writerEpochText,
+        maxSegmentBytes: this.#options.maxSegmentBytes ?? DEFAULT_LOG_SEGMENT_BYTES,
+        compressionLevel: this.#options.compressionLevel ?? DEFAULT_LOG_COMPRESSION_LEVEL,
+        retentionAgeMs: (this.#options.retentionDays ?? DEFAULT_LOG_RETENTION_DAYS) * 24 * 60 * 60 * 1000,
+        retentionBytes: this.#options.retentionBytes ?? DEFAULT_LOG_RETENTION_BYTES
+      }
+    })
+    this.#worker = worker
+    if (this.#pending.length === 0 && this.#inFlight === undefined && this.#flushWaiters.length === 0) worker.unref()
+    let failureHandled = false
+    const fail = (/** @type {unknown} */ error) => {
+      if (failureHandled || generation !== this.#workerGeneration) return
+      failureHandled = true
+      const failure = error instanceof Error ? error : new Error("Compressed log worker failed")
+      void worker.terminate().then(
+        () => this.#handleWorkerFailure(failure, generation),
+        (terminationError) => this.#handleWorkerFailure(terminationError instanceof Error ? terminationError : failure, generation)
+      )
+    }
+    worker.on("message", (message) => {
+      if (generation !== this.#workerGeneration) return
+      if (message?.type === "ready") {
+        this.#workerReady = true
+        this.#state = "healthy"
+        const recoveredHighWater = parseSequence(message.durableHighWater)
+        if (recoveredHighWater > this.#acceptedHighWater) { fail(new Error("Compressed log worker recovered beyond producer high-water")); return }
+        if (this.#inFlight !== undefined && recoveredHighWater === this.#inFlight.lastSequence) {
+          if (!durableBatchMatches(message.lastDurableBatch, this.#inFlight)) { fail(new Error("Compressed log worker recovered a conflicting batch identity")); return }
+        } else if (recoveredHighWater !== this.#durableHighWater) { fail(new Error("Compressed log worker recovered an unexpected durable high-water")); return }
+        this.#durableHighWater = recoveredHighWater
+        if (this.#inFlight !== undefined && this.#inFlight.lastSequence <= recoveredHighWater) this.#releaseInFlight(this.#inFlight.batchId)
+        else this.#postInFlight()
+        if (Number.isSafeInteger(message.orphanRecoveredCount) && message.orphanRecoveredCount > 0) this.#enqueueInternal("log_orphan_recovered", {})
+        if (restart) {
+          this.#enqueueInternal("log_worker_restarted", {attempt: this.#workerRestarts.length})
+          this.#enqueueInternal("log_sink_recovered", {attempt: this.#workerRestarts.length})
+        }
+        this.#settleFlushWaiters()
+        if (this.#inFlight === undefined) this.#sendNext()
+        return
+      }
+      if (message?.type === "ack") {
+        if (!this.#workerReady || this.#inFlight === undefined || message.batchId !== this.#inFlight.batchId) { fail(new Error("Compressed log worker acknowledged an unknown batch")); return }
+        const highWater = parseSequence(message.durableHighWater)
+        if (highWater !== this.#inFlight.lastSequence) { fail(new Error("Compressed log worker durable high-water mismatch")); return }
+        if (!durableBatchMatches(message.lastDurableBatch, this.#inFlight)) { fail(new Error("Compressed log worker durable batch identity mismatch")); return }
+        const lifecycleSource = this.#inFlight.lifecycleSource
+        this.#durableHighWater = highWater
+        this.#releaseInFlight(message.batchId)
+        if (lifecycleSource) this.#enqueueInternal("log_frame_committed", {queuedBytes: this.#pendingBytes})
+        this.#settleFlushWaiters()
+        if (this.#pending.length > 0) this.#sendNext()
+        else if (this.#flushWaiters.length === 0) worker.unref()
+        return
+      }
+      if (message?.type === "closed") {
+        this.#workerReady = false
+        this.#resolveWorkerClosed?.()
+        this.#resolveWorkerClosed = undefined
+        this.#rejectWorkerClosed = undefined
+        return
+      }
+      if (message?.type === "failed") fail(new Error("Compressed log worker reported durable sink failure"))
+    })
+    worker.once("error", fail)
+    worker.once("exit", (code) => {
+      if (this.#state === "closing" && this.#resolveWorkerClosed === undefined && code === 0) return
+      if (this.#state === "closed") return
+      if (!failureHandled && code !== 0) fail(new Error(`Compressed log worker exited with code ${code}`))
+    })
+  }
+
+  /** @param {string} batchId - Acknowledged durable batch. */
+  #releaseInFlight(batchId) {
+    if (this.#inFlight?.batchId !== batchId) return
+    this.#inFlight = undefined
+    this.#inFlightBytes = 0
+  }
+
+  /**
+   * @param {Error} error - Worker failure. @param {number} generation - Worker generation.
+   * @param generation
+   */
+  #handleWorkerFailure(error, generation) {
+    if (generation !== this.#workerGeneration || this.#state === "failed" || this.#state === "closed") return
+    this.#workerReady = false
+    this.#worker = undefined
+    this.#rejectWorkerClosed?.(error)
+    this.#resolveWorkerClosed = undefined
+    this.#rejectWorkerClosed = undefined
+    const now = Date.now()
+    this.#workerRestarts = this.#workerRestarts.filter((time) => now - time <= 60_000)
+    if (!this.#accepting || this.#workerRestarts.length >= 3) {
+      this.#fail(error)
+      return
+    }
+    this.#workerRestarts.push(now)
+    this.#state = "degraded"
+    this.#spawnWorker(true)
+  }
+
+  #settleFlushWaiters() {
+    if (this.#failure !== undefined) {
+      for (const waiter of this.#flushWaiters.splice(0)) waiter.reject(this.#failure)
+      return
+    }
+    if (!this.#workerReady) return
+    const remaining = []
+    for (const waiter of this.#flushWaiters) {
+      if (this.#durableHighWater >= waiter.barrier) waiter.resolve()
+      else remaining.push(waiter)
+    }
+    this.#flushWaiters = remaining
+  }
+
+  /** @param {Error} error - Terminal sink failure. */
+  #fail(error) {
+    this.#failure = error
+    this.#state = "failed"
+    this.#clearFlushTimer()
+    this.#settleFlushWaiters()
+    if (!this.#failureReported) {
+      this.#failureReported = true
+      try { (this.#options.stderr ?? process.stderr).write("Socketduct logger failure (LOG_COMPRESSED_SINK_FAILED)\n") } catch { /* recursive logger failure is intentionally suppressed */ }
+    }
+  }
+
+  /** @param {boolean} critical - Event class. */
+  #recordDrop(critical) {
+    if (critical) this.#criticalDrops += 1
+    else this.#noncriticalDrops += 1
+  }
+
+  /**
+   * Queues a bounded sink-lifecycle record without recursively producing more sink events.
+   * @param {string} event - Internal event name.
+   * @param {Record<string, unknown>} fields - Safe counters.
+   */
+  #enqueueInternal(event, fields) {
+    if (this.#state === "failed" || this.#state === "closed") return false
+    const sequence = this.#acceptedHighWater + 1n
+    const line = formatDiagnosticLogLine({
+      role: this.#options.role,
+      ...(this.#options.processId === undefined ? {} : {processId: this.#options.processId}),
+      ...(this.#options.now === undefined ? {} : {now: this.#options.now}),
+      event,
+      fields,
+      envelope: {writerEpoch: this.#writerEpochText, eventSequence: sequence.toString()}
+    })
+    if (line === undefined) return false
+    const buffer = Buffer.from(line)
+    const charge = conservativeCharge(buffer.length)
+    const maxQueueBytes = this.#options.maxQueueBytes ?? DEFAULT_LOG_QUEUE_BYTES
+    if (this.#pendingBytes + this.#inFlightBytes + charge > maxQueueBytes) {
+      this.#criticalDrops += 1
+      return false
+    }
+    this.#acceptedHighWater = sequence
+    this.#pending.push({event, key: event, sequence, buffer, charge, internal: true})
+    this.#pendingBytes += charge
+    this.#pendingRawBytes += buffer.length
+    this.#worker?.ref()
+    return true
+  }
+}
+
+/**
+ * Creates the managed compressed diagnostic sink.
+ * @param options
+ */
+export function createCompressedJsonlFileLogger(/** @type {CompressedJsonlFileLoggerOptions} */ options) {
+  return new CompressedJsonlFileLogger(options)
+}
+
+/** @param {CompressedJsonlFileLoggerOptions} options - Candidate options. */
+function validateOptions(options) {
+  if (typeof options !== "object" || options === null || typeof options.directory !== "string" || options.directory.trim().length === 0) throw new TypeError("directory must be a non-empty string")
+  if (typeof options.role !== "string" || !ROLE.test(options.role)) throw new TypeError("role must be 1-64 lowercase letters, digits, or hyphens")
+  boundedInteger(options.processId ?? process.pid, "processId", 0, Number.MAX_SAFE_INTEGER)
+  boundedInteger(options.frameMaxBytes ?? DEFAULT_LOG_FRAME_BYTES, "frameMaxBytes", 128, 16 * 1024 * 1024)
+  boundedInteger(options.flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS, "flushIntervalMs", 1, 60_000)
+  boundedInteger(options.criticalFlushIntervalMs ?? DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS, "criticalFlushIntervalMs", 1, 60_000)
+  boundedInteger(options.maxSegmentBytes ?? DEFAULT_LOG_SEGMENT_BYTES, "maxSegmentBytes", 1024, 4 * 1024 * 1024 * 1024)
+  boundedInteger(options.retentionDays ?? DEFAULT_LOG_RETENTION_DAYS, "retentionDays", 1, 3650)
+  const retentionBytes = boundedInteger(options.retentionBytes ?? DEFAULT_LOG_RETENTION_BYTES, "retentionBytes", 1024, 1024 * 1024 * 1024 * 1024)
+  const maxQueueBytes = boundedInteger(options.maxQueueBytes ?? DEFAULT_LOG_QUEUE_BYTES, "maxQueueBytes", 1024, 1024 * 1024 * 1024)
+  const criticalReserveBytes = boundedInteger(options.criticalReserveBytes ?? DEFAULT_LOG_CRITICAL_RESERVE_BYTES, "criticalReserveBytes", 0, maxQueueBytes - 1)
+  if (maxQueueBytes - criticalReserveBytes < 512) throw new RangeError("noncritical log queue must retain at least 512 bytes")
+  if ((options.maxSegmentBytes ?? DEFAULT_LOG_SEGMENT_BYTES) > retentionBytes) throw new RangeError("maxSegmentBytes must not exceed retentionBytes")
+}
+
+/**
+ * @param {number} value - Candidate. @param {string} name - Field. @param {number} minimum - Inclusive minimum. @param {number} maximum - Inclusive maximum.
+ * @param name
+ * @param minimum
+ * @param maximum
+ */
+function boundedInteger(value, name, minimum, maximum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) throw new RangeError(`${name} must be an integer from ${minimum} to ${maximum}`)
+  return value
+}
+
+/** @param {number} bytes - Raw JSONL bytes. */
+function conservativeCharge(bytes) {
+  return bytes * 3 + 128
+}
+
+/**
+ * @param {string} event - Event name. @param {Record<string, unknown>} fields - Safe diagnostic fields.
+ * @param fields
+ */
+function coalesceKey(event, fields) {
+  const member = typeof fields.gatewayId === "string" ? fields.gatewayId : typeof fields.routeClass === "string" ? fields.routeClass : ""
+  return `${event}\0${member}`
+}
+
+/** @param {unknown} value - Serialized sequence. */
+function parseSequence(value) {
+  if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(value)) throw new Error("Invalid compressed log durable high-water")
+  return BigInt(value)
+}
+
+/**
+ * @param {unknown} value - Worker-reported last durable batch.
+ * @param {{batchId: string, firstSequence: bigint, lastSequence: bigint}} batch - Producer batch.
+ */
+function durableBatchMatches(value, batch) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  const candidate = /** @type {Record<string, unknown>} */ (value)
+  return candidate.batchId === batch.batchId && candidate.firstSequence === batch.firstSequence.toString() && candidate.lastSequence === batch.lastSequence.toString()
+}

package/src/logging/log-batch.js

@@ -0,0 +1,72 @@
+/* eslint-disable jsdoc/require-param-type, jsdoc/require-returns */
+import {createHash} from "node:crypto"
+
+/**
+ * Computes the normative deterministic 128-bit batch identity.
+ * @param writerEpoch
+ * @param firstSequence
+ * @param lastSequence
+ * @param jsonl
+ */
+export function createLogBatchId(/** @type {Buffer | Uint8Array} */ writerEpoch, /** @type {bigint} */ firstSequence, /** @type {bigint} */ lastSequence, /** @type {Buffer | Uint8Array} */ jsonl) {
+  if (!(writerEpoch instanceof Uint8Array) || writerEpoch.byteLength !== 16) throw new TypeError("writerEpoch must contain exactly 16 bytes")
+  if (typeof firstSequence !== "bigint" || firstSequence < 1n || typeof lastSequence !== "bigint" || lastSequence < firstSequence) throw new RangeError("batch sequence range is invalid")
+  if (!(jsonl instanceof Uint8Array) || jsonl.byteLength === 0 || jsonl[jsonl.byteLength - 1] !== 0x0a) throw new TypeError("batch JSONL must be non-empty and newline terminated")
+  const range = Buffer.alloc(16)
+  range.writeBigUInt64BE(firstSequence, 0)
+  range.writeBigUInt64BE(lastSequence, 8)
+  return createHash("sha256")
+    .update("socketduct-log-batch:v1")
+    .update(Buffer.from([0]))
+    .update(writerEpoch)
+    .update(range)
+    .update(jsonl)
+    .digest()
+    .subarray(0, 16)
+}
+
+/**
+ * Validates a complete batch and extracts structural timestamps/sequences.
+ * @param jsonl
+ * @param writerEpoch
+ */
+export function inspectLogBatch(/** @type {Buffer | Uint8Array} */ jsonl, /** @type {Buffer | Uint8Array} */ writerEpoch) {
+  const raw = Buffer.from(jsonl)
+  const epoch = Buffer.from(writerEpoch)
+  if (raw.length === 0 || raw.at(-1) !== 0x0a) throw new Error("Log batch is not complete newline JSONL")
+  const epochText = epoch.toString("base64url")
+  const lines = raw.subarray(0, raw.length - 1).toString("utf8").split("\n")
+  /** @type {Array<Record<string, unknown>>} */
+  const records = []
+  let firstSequence
+  let previousSequence
+  let minTimestamp = Number.POSITIVE_INFINITY
+  let maxTimestamp = Number.NEGATIVE_INFINITY
+  for (const line of lines) {
+    if (line.length === 0) throw new Error("Log batch contains an empty record")
+    const parsed = JSON.parse(line)
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("Log record must be an object")
+    const record = /** @type {Record<string, unknown>} */ (parsed)
+    if (record.writerEpoch !== epochText || typeof record.eventSequence !== "string" || !/^[1-9][0-9]*$/.test(record.eventSequence)) throw new Error("Log record writer identity is invalid")
+    const sequence = BigInt(record.eventSequence)
+    if (previousSequence !== undefined && sequence !== previousSequence + 1n) throw new Error("Log record sequence is not contiguous")
+    firstSequence ??= sequence
+    previousSequence = sequence
+    if (typeof record.timestamp !== "string") throw new Error("Log record timestamp is missing")
+    const timestamp = Date.parse(record.timestamp)
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) throw new Error("Log record timestamp is invalid")
+    minTimestamp = Math.min(minTimestamp, timestamp)
+    maxTimestamp = Math.max(maxTimestamp, timestamp)
+    records.push(record)
+  }
+  if (firstSequence === undefined || previousSequence === undefined) throw new Error("Log batch contains no records")
+  return {
+    records,
+    firstSequence,
+    lastSequence: previousSequence,
+    recordCount: records.length,
+    minTimestamp: BigInt(minTimestamp),
+    maxTimestamp: BigInt(maxTimestamp),
+    batchId: createLogBatchId(epoch, firstSequence, previousSequence, raw)
+  }
+}