socketduct 0.1.19 → 0.1.21

package/test/unit/config/environment.test.js

@@ -79,37 +79,77 @@ test("loadEnvironmentConfig parses or disables the status interval", () => {
   assert.throws(() => loadEnvironmentConfig({SOCKETDUCT_STATUS_INTERVAL_MS: "-1"}), /non-negative integer/)
 })
 
-test("loadEnvironmentConfig keeps persistent logging disabled by default and parses explicit bounds", () => {
+test("loadEnvironmentConfig keeps persistent logging disabled by default and parses compressed bounds", () => {
   assert.equal(loadEnvironmentConfig({}).fileLogging, undefined)
   assert.equal(loadEnvironmentConfig({SOCKETDUCT_LOG_DIRECTORY: "   "}).fileLogging, undefined)
   assert.deepEqual(loadEnvironmentConfig({
     SOCKETDUCT_LOG_DIRECTORY: "  /var/log/socketduct  ",
-    SOCKETDUCT_LOG_MAX_FILE_BYTES: "2097152",
-    SOCKETDUCT_LOG_MAX_FILES: "4"
+    SOCKETDUCT_LOG_FRAME_MAX_BYTES: "2097152",
+    SOCKETDUCT_LOG_FLUSH_INTERVAL_MS: "1500",
+    SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS: "200",
+    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "268435456",
+    SOCKETDUCT_LOG_RETENTION_DAYS: "14",
+    SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "3221225472",
+    SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "33554432",
+    SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "4194304",
+    SOCKETDUCT_LOG_COMPRESSION_LEVEL: "18"
   }).fileLogging, {
     directory: "/var/log/socketduct",
-    maxFileBytes: 2_097_152,
-    maxFiles: 4
+    frameMaxBytes: 2_097_152,
+    flushIntervalMs: 1_500,
+    criticalFlushIntervalMs: 200,
+    maxSegmentBytes: 268_435_456,
+    retentionDays: 14,
+    retentionBytes: 3_221_225_472,
+    maxQueueBytes: 33_554_432,
+    criticalReserveBytes: 4_194_304,
+    compressionLevel: 18
   })
 })
 
-test("loadEnvironmentConfig rejects unsafe persistent logging bounds", () => {
+test("loadEnvironmentConfig rejects unsafe compressed logging bounds", () => {
   assert.throws(() => loadEnvironmentConfig({
     SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_MAX_FILE_BYTES: "100"
-  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
+    SOCKETDUCT_LOG_FRAME_MAX_BYTES: "100"
+  }), /SOCKETDUCT_LOG_FRAME_MAX_BYTES/)
   assert.throws(() => loadEnvironmentConfig({
     SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_MAX_FILE_BYTES: "9007199254740992"
-  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
+    SOCKETDUCT_LOG_COMPRESSION_LEVEL: "23"
+  }), /SOCKETDUCT_LOG_COMPRESSION_LEVEL/)
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_LOG_QUEUE_MAX_BYTES: "1024",
+    SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES: "1024"
+  }), /SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES/)
   assert.throws(() => loadEnvironmentConfig({
     SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_MAX_FILES: "0"
-  }), /SOCKETDUCT_LOG_MAX_FILES/)
+    SOCKETDUCT_LOG_SEGMENT_MAX_BYTES: "5368709120",
+    SOCKETDUCT_LOG_RETENTION_MAX_BYTES: "4294967296"
+  }), /SOCKETDUCT_LOG_SEGMENT_MAX_BYTES/)
   assert.throws(() => loadEnvironmentConfig({
     SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
-    SOCKETDUCT_LOG_MAX_FILES: "101"
-  }), /SOCKETDUCT_LOG_MAX_FILES/)
+    SOCKETDUCT_LOG_MAX_FILE_BYTES: "10485760"
+  }), /SOCKETDUCT_LOG_MAX_FILE_BYTES/)
+})
+
+test("loadEnvironmentConfig accepts a paired hub-only fingerprint key and epoch", () => {
+  const encodedKey = Buffer.alloc(32, 0x5a).toString("base64url")
+  const config = loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-hub",
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct",
+    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
+    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
+  })
+  assert.deepEqual(config.connectionFingerprint, {key: Buffer.alloc(32, 0x5a), keyEpoch: "hub-2026-09"})
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-hub",
+    SOCKETDUCT_LOG_DIRECTORY: "/var/log/socketduct"
+  }), /SOCKETDUCT_CONNECTION_FINGERPRINT_KEY/)
+  assert.throws(() => loadEnvironmentConfig({
+    SOCKETDUCT_MODE: "reverse-gateway",
+    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY: encodedKey,
+    SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH: "hub-2026-09"
+  }), /hub-only/)
 })
 
 test("loadEnvironmentConfig selects v3 explicitly and keeps v2 as rollback default", () => {

package/test/unit/index.test.js

@@ -3,6 +3,7 @@ import test from "node:test"
 
 import {
   connectSocketduct,
+  createCompressedJsonlFileLogger,
   createJsonlFileLogger,
   createMultiplexedSocketductConnection,
   createMultiplexedSocketductTransportSet,
@@ -12,6 +13,7 @@ import {
   MultiplexedSocketductTransportSet,
   OutboundReverseGateway,
   ReverseGatewayConnection,
+  SocketductRecoveryLookupError,
   SocketductHttpAgent,
   SocketductSocket
 } from "../../src/index.js"
@@ -19,6 +21,7 @@ import {createSocketductConnectionFactory as directCreateSocketductConnectionFac
 import {SocketductHttpAgent as DirectSocketductHttpAgent} from "../../src/client/http-agent.js"
 import {connectSocketduct as directConnectSocketduct, SocketductSocket as DirectSocketductSocket} from "../../src/client/socketduct-socket.js"
 import {createJsonlFileLogger as directCreateJsonlFileLogger} from "../../src/logging/structured-logger.js"
+import {createCompressedJsonlFileLogger as directCreateCompressedJsonlFileLogger} from "../../src/logging/compressed-log-writer.js"
 
 test("getStartupSummary returns the Socketduct service identity and default mode", () => {
   assert.deepEqual(getStartupSummary(), {
@@ -33,6 +36,7 @@ test("index exports the public SocketductSocket client API", () => {
   assert.equal(connectSocketduct, directConnectSocketduct)
   assert.equal(createSocketductConnectionFactory, directCreateSocketductConnectionFactory)
   assert.equal(createJsonlFileLogger, directCreateJsonlFileLogger)
+  assert.equal(createCompressedJsonlFileLogger, directCreateCompressedJsonlFileLogger)
   assert.equal(SocketductHttpAgent, DirectSocketductHttpAgent)
 })
 
@@ -54,6 +58,7 @@ test("package exports the protocol-v3 pooled connection and relay entrypoints",
 
   assert.equal(multiplexed.MultiplexedSocketductConnection, MultiplexedSocketductConnection)
   assert.equal(multiplexed.MultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet)
+  assert.equal(multiplexed.SocketductRecoveryLookupError, SocketductRecoveryLookupError)
   assert.equal(createMultiplexedSocketductConnection({
     relay: {host: "127.0.0.1", port: 3100, token: "test-token"}
   }) instanceof MultiplexedSocketductConnection, true)

package/test/unit/logging/compressed-log-worker.test.js

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {writeAll} from "../../../src/logging/compressed-log-worker.js"
+
+test("worker positional writes preserve every byte across all short-write offsets", async () => {
+  const source = Buffer.from("short-write-safe-durable-frame")
+  for (let maximum = 1; maximum <= source.length; maximum += 1) {
+    const destination = Buffer.alloc(source.length + 7)
+    /** @type {number[]} */
+    const positions = []
+    const handle = {
+      async write(/** @type {Buffer} */ bytes, /** @type {number} */ offset, /** @type {number} */ length, /** @type {number} */ position) {
+        const bytesWritten = Math.min(maximum, length)
+        positions.push(position)
+        Buffer.from(bytes).copy(destination, position, offset, offset + bytesWritten)
+        return {bytesWritten, buffer: bytes}
+      }
+    }
+    await writeAll(/** @type {import('node:fs/promises').FileHandle} */ (handle), source, 7)
+    assert.deepEqual(destination.subarray(7), source)
+    assert.deepEqual(positions, Array.from({length: Math.ceil(source.length / maximum)}, (_, index) => 7 + index * maximum))
+  }
+})
+
+test("worker positional writes fail loudly on zero progress", async () => {
+  const handle = {async write(/** @type {Buffer} */ bytes) { return {bytesWritten: 0, buffer: bytes} }}
+  await assert.rejects(() => writeAll(/** @type {import('node:fs/promises').FileHandle} */ (handle), Buffer.from("frame"), 0), /no progress/)
+})

package/test/unit/logging/compressed-log-writer.test.js

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict"
+import {mkdtemp, readdir, rm, stat} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {readCompressedLogDirectory} from "../../../src/logging/compressed-log-reader.js"
+import {createCompressedJsonlFileLogger} from "../../../src/logging/compressed-log-writer.js"
+
+test("compressed logger durably acknowledges ordered records and closes asynchronously", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-writer-"))
+  const directory = join(root, "logs")
+  let tick = 0
+  const logger = createCompressedJsonlFileLogger({
+    directory,
+    role: "reverse-hub",
+    now: () => new Date(1_795_000_000_000 + tick++),
+    frameMaxBytes: 256,
+    flushIntervalMs: 60_000,
+    criticalFlushIntervalMs: 60_000,
+    maxSegmentBytes: 2048
+  })
+  t.after(async () => { await logger.close().catch(() => {}); await rm(root, {recursive: true, force: true}) })
+
+  assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub", token: "must-not-survive"}), "accepted")
+  assert.equal(logger.log("runtime.status", {virtualStreams: 4}), "accepted")
+  assert.equal(logger.log("runtime.status", {virtualStreams: 5}), "accepted")
+  assert.equal(logger.status().acceptedHighWater, "3")
+  await logger.flush()
+
+  const durable = logger.status()
+  assert(Number(durable.durableHighWater) >= 3)
+  assert.equal(durable.health, "healthy")
+  const result = await readCompressedLogDirectory(directory)
+  assert.equal(result.incomplete, false)
+  assert.deepEqual(result.records.map((record) => record.eventSequence), Array.from({length: result.records.length}, (_, index) => String(index + 1)))
+  assert.deepEqual(result.records.filter((record) => !String(record.event).startsWith("log_")).map((record) => record.event), ["process.started", "runtime.status", "runtime.status"])
+  assert.equal(new Set(result.records.map((record) => record.writerEpoch)).size, 1)
+  assert.doesNotMatch(JSON.stringify(result.records), /must-not-survive/)
+
+  const filesBeforeClose = await readdir(directory)
+  assert(filesBeforeClose.some((name) => name.endsWith(".jsonl.zst")))
+  assert(filesBeforeClose.some((name) => name.endsWith(".jsonl.zst.idx")))
+  assert.equal(filesBeforeClose.some((name) => name.endsWith(".jsonl")), false)
+  assert.equal((await stat(directory)).mode & 0o777, 0o700)
+  for (const name of filesBeforeClose) assert.equal((await stat(join(directory, name))).mode & 0o777, 0o600)
+
+  const firstClose = logger.close()
+  const secondClose = logger.close()
+  assert.equal(firstClose, secondClose)
+  const finalStatus = await firstClose
+  assert.equal(finalStatus.state, "closed")
+  assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub"}), "dropped")
+  assert((await readdir(directory)).some((name) => name.endsWith(".jsonl.zst.sealed")))
+  const closed = await readCompressedLogDirectory(directory)
+  assert(closed.records.some((record) => record.event === "log_batch_accepted"))
+  assert(closed.records.some((record) => record.event === "log_frame_committed"))
+  assert.equal(closed.records.at(-1)?.event, "log_closed")
+})
+
+test("compressed logger enforces one shared bounded queue with a critical reserve", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-pressure-"))
+  const directory = join(root, "logs")
+  const logger = createCompressedJsonlFileLogger({
+    directory,
+    role: "reverse-client",
+    maxQueueBytes: 4096,
+    criticalReserveBytes: 1024,
+    frameMaxBytes: 1024,
+    flushIntervalMs: 60_000,
+    criticalFlushIntervalMs: 60_000
+  })
+  t.after(async () => { await logger.close().catch(() => {}); await rm(root, {recursive: true, force: true}) })
+
+  const outcomes = Array.from({length: 40}, () => logger.log("runtime.status", {virtualStreams: 1}))
+  assert(outcomes.includes("dropped") || outcomes.includes("coalesced"))
+  assert(logger.status().queuedBytes <= 4096)
+  assert.equal(logger.log("transport.disconnected", {
+    clientConnectionGeneration: 1,
+    disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
+    disconnectReason: "remote_eof",
+    incidentOrigin: "reverse_client",
+    physicalRole: "client",
+    fanOutCount: 1,
+    resumeSuccessCount: 0,
+    terminalStreamCount: 0
+  }), "accepted")
+  assert(logger.status().queuedBytes <= 4096)
+  await logger.flush()
+})
+
+test("compressed logger caps worker restarts and retains only bounded critical evidence after failure", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-worker-death-"))
+  const directory = join(root, "logs")
+  const logger = createCompressedJsonlFileLogger({
+    directory,
+    role: "reverse-hub",
+    frameMaxBytes: 256,
+    maxSegmentBytes: 1024,
+    maxQueueBytes: 65_536,
+    criticalReserveBytes: 8192,
+    flushIntervalMs: 60_000,
+    criticalFlushIntervalMs: 60_000,
+    stderr: {write: () => true}
+  })
+  t.after(async () => { await logger.close().catch(() => {}); await rm(root, {recursive: true, force: true}) })
+  logger.log("process.started", {runtimeMode: "reverse-hub"})
+  await logger.flush()
+  await rm(directory, {recursive: true, force: true})
+
+  for (let index = 0; index < 20; index += 1) logger.log("process.started", {runtimeMode: "reverse-hub"})
+  await assert.rejects(() => logger.flush())
+  assert.equal(logger.status().state, "failed")
+  assert.equal(logger.status().workerRestarts, 3)
+  assert.equal(logger.log("runtime.status", {virtualStreams: 1}), "dropped")
+  assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub"}), "accepted")
+  assert(logger.status().allocatedBytes <= 65_536)
+})
+
+test("compressed logger flush is a caller-time durability barrier", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-barrier-"))
+  const logger = createCompressedJsonlFileLogger({
+    directory: join(root, "logs"),
+    role: "reverse-hub",
+    frameMaxBytes: 256,
+    flushIntervalMs: 60_000,
+    criticalFlushIntervalMs: 60_000,
+    maxQueueBytes: 1_000_000,
+    criticalReserveBytes: 1024
+  })
+  t.after(async () => { await logger.close().catch(() => {}); await rm(root, {recursive: true, force: true}) })
+  await logger.flush()
+  assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub"}), "accepted")
+  const barrier = logger.flush()
+  for (let index = 0; index < 8; index += 1) assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub"}), "accepted")
+  await barrier
+  const status = logger.status()
+  assert(BigInt(status.durableHighWater) >= 1n)
+  assert(BigInt(status.durableHighWater) < BigInt(status.acceptedHighWater))
+})
+
+test("compressed logger flushes immediately at frame size and critical deadlines do not slide", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-deadline-"))
+  const directory = join(root, "logs")
+  const logger = createCompressedJsonlFileLogger({
+    directory,
+    role: "reverse-hub",
+    frameMaxBytes: 256,
+    flushIntervalMs: 60_000,
+    criticalFlushIntervalMs: 40,
+    maxQueueBytes: 1_000_000,
+    criticalReserveBytes: 1024
+  })
+  t.after(async () => { await logger.close().catch(() => {}); await rm(root, {recursive: true, force: true}) })
+  await logger.flush()
+
+  assert.equal(logger.log("runtime.status", {virtualStreams: 1}), "accepted")
+  assert.equal(logger.log("process.started", {runtimeMode: "reverse-hub"}), "accepted")
+  await waitUntil(() => BigInt(logger.status().durableHighWater) > 0n, 1_000)
+
+  await logger.flush()
+  const before = BigInt(logger.status().durableHighWater)
+  const producer = setInterval(() => logger.log("process.started", {runtimeMode: "reverse-hub"}), 5)
+  try {
+    await waitUntil(() => BigInt(logger.status().durableHighWater) > before, 500)
+  } finally {
+    clearInterval(producer)
+  }
+  const durable = await readCompressedLogDirectory(directory)
+  assert(durable.records.some((record) => record.event === "runtime.status"))
+})
+
+/**
+ * @param {() => boolean} predicate - Completion predicate.
+ * @param {number} timeoutMs - Deadline.
+ */
+async function waitUntil(predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) assert.fail("timed out waiting for compressed logger progress")
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+}

package/test/unit/logging/log-retention.test.js

@@ -0,0 +1,86 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {readlinkSync} from "node:fs"
+import {mkdtemp, readFile, readdir, rm, utimes, writeFile} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {enforceLogRetention} from "../../../src/logging/log-retention.js"
+
+test("retention removes only oldest sealed segments and preserves active evidence", async (t) => {
+  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-"))
+  t.after(() => rm(directory, {recursive: true, force: true}))
+  const old = await createSegment(directory, "reverse-hub-AAAAAAAAAAAAAAAAAAAAAA-123e4567-e89b-42d3-a456-426614174000", 700, true)
+  const newer = await createSegment(directory, "reverse-hub-BBBBBBBBBBBBBBBBBBBBBB-123e4567-e89b-42d3-a456-426614174001", 700, true)
+  const active = await createSegment(directory, "reverse-hub-CCCCCCCCCCCCCCCCCCCCCC-123e4567-e89b-42d3-a456-426614174002", 700, false)
+  await utimes(old.data, new Date(1_000), new Date(1_000))
+  await utimes(newer.data, new Date(2_000), new Date(2_000))
+  await utimes(active.data, new Date(3_000), new Date(3_000))
+
+  const result = await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1800, now: () => new Date(3_000)})
+  const names = await readdir(directory)
+  assert.equal(names.some((name) => name.startsWith(old.name)), false)
+  assert(names.some((name) => name.startsWith(newer.name)))
+  assert(names.some((name) => name.startsWith(active.name)))
+  assert.equal(result.deletedSegments, 1)
+})
+
+test("retention fails closed when active or quarantined bytes prevent quota compliance", async (t) => {
+  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-blocked-"))
+  t.after(() => rm(directory, {recursive: true, force: true}))
+  const active = await createSegment(directory, "reverse-client-DDDDDDDDDDDDDDDDDDDDDD-123e4567-e89b-42d3-a456-426614174003", 1800, false)
+  await writeFile(`${active.data}.quarantine`, "LOG_EVIDENCE_INVALID", {mode: 0o600})
+
+  await assert.rejects(
+    () => enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024, now: () => new Date(3_000)}),
+    (error) => error instanceof Error && /** @type {{code?: unknown}} */ (error).code === "LOG_RETENTION_QUOTA_BLOCKED"
+  )
+  assert((await readdir(directory)).some((name) => name.startsWith(active.name)))
+})
+
+test("retention reclaims stale ownership without displacing a live process instance", async (t) => {
+  const directory = await mkdtemp(join(tmpdir(), "socketduct-retention-owner-"))
+  t.after(() => rm(directory, {recursive: true, force: true}))
+  const lockPath = join(directory, ".socketduct-retention.lock")
+  const processStart = processStartIdentity(await readFile(`/proc/${process.pid}/stat`, "utf8"))
+  const tid = Number(readlinkSync("/proc/thread-self").split("/").at(-1))
+  const threadStart = processStartIdentity(await readFile(`/proc/${process.pid}/task/${tid}/stat`, "utf8"))
+  const staleTemporary = `.socketduct-retention-owner-${process.pid}-${BigInt(processStart) + 1n}-${tid}-${threadStart}-123e4567-e89b-42d3-a456-426614174099.tmp`
+  await writeFile(join(directory, staleTemporary), "incomplete", {mode: 0o600})
+
+  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart: String(BigInt(processStart) + 1n), tid, threadStart})}\n`, {mode: 0o600})
+  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, false)
+  assert.equal((await readdir(directory)).includes(staleTemporary), false)
+
+  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid: 2_147_483_647, threadStart: "1"})}\n`, {mode: 0o600})
+  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, false)
+
+  await writeFile(lockPath, `${JSON.stringify({version: 1, pid: process.pid, processStart, tid, threadStart})}\n`, {mode: 0o600})
+  assert.equal((await enforceLogRetention({directory, maxAgeMs: 60_000, maxBytes: 1024})).skipped, true)
+})
+
+/**
+ * @param {string} directory - Fixture directory. @param {string} stem - Segment stem. @param {number} bytes - Data bytes. @param {boolean} sealed - Whether to seal.
+ * @param stem
+ * @param bytes
+ * @param sealed
+ */
+async function createSegment(directory, stem, bytes, sealed) {
+  const name = `${stem}.jsonl.zst`
+  const data = join(directory, name)
+  await writeFile(data, Buffer.alloc(bytes), {mode: 0o600})
+  await writeFile(`${data}.idx`, Buffer.alloc(48), {mode: 0o600})
+  if (sealed) await writeFile(`${data}.sealed`, "", {mode: 0o600})
+  return {name, data}
+}
+
+/** @param {string} value - Linux proc stat contents. @returns {string} Kernel process start ticks. */
+function processStartIdentity(value) {
+  const close = value.lastIndexOf(")")
+  const fields = value.slice(close + 2).trim().split(/\s+/)
+  const start = fields[19]
+  if (start === undefined) assert.fail("process stat omits start time")
+  assert.match(start, /^[0-9]+$/)
+  return start
+}

package/test/unit/logging/log-segment-index.test.js

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict"
+import {createHash, randomBytes} from "node:crypto"
+import test from "node:test"
+
+import {
+  INDEX_ENTRY_BYTES,
+  INDEX_HEADER_BYTES,
+  createIndexEntry,
+  createIndexHeader,
+  parseIndexEntry,
+  parseIndexHeader,
+  uuidBytes
+} from "../../../src/logging/log-segment-index.js"
+
+test("index v1 header and entry round-trip in the exact fixed-width format", () => {
+  const segmentUuid = uuidBytes("123e4567-e89b-42d3-a456-426614174000")
+  const writerEpoch = randomBytes(16)
+  const batchId = randomBytes(16)
+  const frameHash = createHash("sha256").update("frame").digest()
+  const header = createIndexHeader({segmentUuid, writerEpoch})
+  const entry = createIndexEntry({
+    segmentUuid,
+    writerEpoch,
+    batchId,
+    firstSequence: 1n,
+    lastSequence: 3n,
+    dataOffset: 0n,
+    compressedLength: 91n,
+    uncompressedLength: 240n,
+    recordCount: 3,
+    minTimestamp: 1_795_000_000_000n,
+    maxTimestamp: 1_795_000_000_010n,
+    frameSha256: frameHash
+  })
+
+  assert.equal(header.length, INDEX_HEADER_BYTES)
+  assert.equal(entry.length, INDEX_ENTRY_BYTES)
+  assert.deepEqual(parseIndexHeader(header), {version: 1, segmentUuid, writerEpoch})
+  assert.deepEqual(parseIndexEntry(entry, {segmentUuid, writerEpoch}), {
+    version: 1,
+    flags: 0,
+    segmentUuid,
+    writerEpoch,
+    batchId,
+    firstSequence: 1n,
+    lastSequence: 3n,
+    dataOffset: 0n,
+    compressedLength: 91n,
+    uncompressedLength: 240n,
+    recordCount: 3,
+    minTimestamp: 1_795_000_000_000n,
+    maxTimestamp: 1_795_000_000_010n,
+    frameSha256: frameHash
+  })
+})
+
+test("index CRC and identity corruption fail closed", () => {
+  const segmentUuid = randomBytes(16)
+  const writerEpoch = randomBytes(16)
+  const header = createIndexHeader({segmentUuid, writerEpoch})
+  header[20] = /** @type {number} */ (header[20]) ^ 0xff
+  assert.throws(() => parseIndexHeader(header), /CRC32C/)
+
+  const entry = createIndexEntry({
+    segmentUuid,
+    writerEpoch,
+    batchId: randomBytes(16),
+    firstSequence: 8n,
+    lastSequence: 8n,
+    dataOffset: 10n,
+    compressedLength: 20n,
+    uncompressedLength: 30n,
+    recordCount: 1,
+    minTimestamp: 4n,
+    maxTimestamp: 4n,
+    frameSha256: randomBytes(32)
+  })
+  entry[151] = /** @type {number} */ (entry[151]) ^ 0xff
+  assert.throws(() => parseIndexEntry(entry, {segmentUuid, writerEpoch}), /CRC32C/)
+})
+
+test("index bytes contain no searchable diagnostic dimensions", () => {
+  const forbidden = ["minisforum-zyxel", "disconnect-incident", "GATEWAY_DISCONNECTED", "docker.internal"]
+  const segmentUuid = randomBytes(16)
+  const writerEpoch = randomBytes(16)
+  const encoded = Buffer.concat([
+    createIndexHeader({segmentUuid, writerEpoch}),
+    createIndexEntry({
+      segmentUuid,
+      writerEpoch,
+      batchId: randomBytes(16),
+      firstSequence: 1n,
+      lastSequence: 1n,
+      dataOffset: 0n,
+      compressedLength: 1n,
+      uncompressedLength: 1n,
+      recordCount: 1,
+      minTimestamp: 1n,
+      maxTimestamp: 1n,
+      frameSha256: randomBytes(32)
+    })
+  ])
+  for (const value of forbidden) assert.equal(encoded.includes(Buffer.from(value)), false)
+})

package/test/unit/logging/structured-logger.test.js

@@ -3,7 +3,7 @@ import {chmod, mkdtemp, mkdir, readFile, readdir, rename, rm, stat, utimes, writ
 import {tmpdir} from "node:os"
 import {join} from "node:path"
 
-import {createJsonlFileLogger, createStructuredLogger, errorDiagnostics, logDiagnostic} from "../../../src/logging/structured-logger.js"
+import {createJsonlFileLogger, createStructuredLogger, errorDiagnostics, formatDiagnosticLogLine, logDiagnostic} from "../../../src/logging/structured-logger.js"
 
 const FIXED_TIME = "2026-09-05T12:34:56.789Z"
 
@@ -21,6 +21,19 @@ function parseLines(contents) {
 }
 
 describe("structured logger", {timeoutMs: 15000}, () => {
+  it("accepts only the exact producer-owned compressed envelope", () => {
+    expect(() => formatDiagnosticLogLine({
+      role: "reverse-hub",
+      event: "process.started",
+      envelope: /** @type {{writerEpoch: string, eventSequence: string}} */ ({writerEpoch: "AAAAAAAAAAAAAAAAAAAAAA", eventSequence: "1", role: "peer-role"})
+    })).toThrow(/envelope/)
+    expect(() => formatDiagnosticLogLine({
+      role: "reverse-hub",
+      event: "process.started",
+      envelope: {writerEpoch: "not-canonical", eventSequence: "1"}
+    })).toThrow(/writerEpoch/)
+  })
+
   it("structured logger writes one allowlisted bounded JSON object per line", () => {
     /** @type {string[]} */
     const lines = []

package/test/unit/logging/zstd-frame-codec.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {compressLogFrame, decompressLogFrame} from "../../../src/logging/zstd-frame-codec.js"
+
+test("log codec emits independently decodable standard zstd frames with checksums at level 19", async () => {
+  const firstRaw = Buffer.from('{"event":"first"}\n')
+  const secondRaw = Buffer.from('{"event":"second"}\n')
+  const first = await compressLogFrame(firstRaw)
+  const second = await compressLogFrame(secondRaw)
+
+  assert.deepEqual(first.subarray(0, 4), Buffer.from([0x28, 0xb5, 0x2f, 0xfd]))
+  assert.notEqual(/** @type {number} */ (first[4]) & 0x04, 0, "zstd frame checksum flag must be set")
+  assert.deepEqual(await decompressLogFrame(first), firstRaw)
+  assert.deepEqual(await decompressLogFrame(second), secondRaw)
+  assert.notDeepEqual(first, second)
+})
+
+test("log codec never falls back to plaintext", async () => {
+  const raw = Buffer.from("small\n")
+  const frame = await compressLogFrame(raw)
+  assert.equal(frame.equals(raw), false)
+  await assert.rejects(() => decompressLogFrame(Buffer.from("small\n")))
+})