socketduct 0.1.19 → 0.1.20

package/test/integration/logging-cli.test.js

@@ -0,0 +1,168 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {execFile, spawn} from "node:child_process"
+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 {promisify} from "node:util"
+
+import {createCompressedJsonlFileLogger} from "../../src/logging/compressed-log-writer.js"
+import {CompressedLogTailReader} from "../../src/logging/compressed-log-reader.js"
+import {enforceLogRetention} from "../../src/logging/log-retention.js"
+
+const run = promisify(execFile)
+const cli = new URL("../../src/cli/socketduct.js", import.meta.url)
+
+test("owned CLI searches and tails durable compressed records with stable exits", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-logs-cli-"))
+  const directory = join(root, "logs")
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const logger = createCompressedJsonlFileLogger({directory, role: "reverse-hub"})
+  logger.log("process.started", {runtimeMode: "reverse-hub"})
+  logger.log("runtime.status", {virtualStreams: 7})
+  await logger.close()
+
+  const match = await invoke("logs", "search", "--directory", directory, "--event", "runtime.status")
+  assert.equal(match.code, 0)
+  assert.deepEqual(match.stdout.trim().split("\n").map((line) => JSON.parse(line).event), ["runtime.status"])
+
+  const absent = await invoke("logs", "search", "--directory", directory, "--event", "transport.failed")
+  assert.equal(absent.code, 1)
+  assert.equal(absent.stdout, "")
+
+  const tail = await invoke("logs", "tail", "--directory", directory)
+  assert.equal(tail.code, 0)
+  assert.deepEqual(tail.stdout.trim().split("\n").map((line) => JSON.parse(line).event), ["process.started", "runtime.status", "log_batch_accepted", "log_frame_committed", "log_closed"])
+
+  const invalid = await invoke("logs", "search", "--directory", directory, "--client-generation", "not-a-number")
+  assert.equal(invalid.code, 2)
+  assert.match(invalid.stderr, /Socketduct logs error/)
+})
+
+test("owned CLI follow stays live and emits newly durable writer records", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-logs-follow-"))
+  const directory = join(root, "logs")
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const initial = createCompressedJsonlFileLogger({directory, role: "reverse-client"})
+  initial.log("process.started", {runtimeMode: "reverse-client"})
+  await initial.close()
+
+  const child = spawn(process.execPath, [cli.pathname, "logs", "tail", "--directory", directory, "--follow", "--poll-ms", "10"], {stdio: ["ignore", "pipe", "pipe"]})
+  let stdout = ""
+  let stderr = ""
+  child.stdout.on("data", (chunk) => { stdout += chunk.toString() })
+  child.stderr.on("data", (chunk) => { stderr += chunk.toString() })
+  t.after(() => { if (child.exitCode === null) child.kill("SIGKILL") })
+  await waitFor(() => stdout.includes('"eventSequence":"1"'), child, () => stderr)
+
+  const later = createCompressedJsonlFileLogger({directory, role: "reverse-client"})
+  later.log("runtime.status", {virtualStreams: 2})
+  await later.close()
+  await waitFor(() => stdout.includes('"event":"runtime.status"'), child, () => stderr)
+  child.kill("SIGTERM")
+  const code = await new Promise((resolve) => child.once("exit", resolve))
+  assert.equal(code, 0)
+})
+
+test("owned CLI exits 2 instead of hiding corrupt interior evidence", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-logs-corrupt-"))
+  const directory = join(root, "logs")
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const logger = createCompressedJsonlFileLogger({directory, role: "reverse-gateway"})
+  logger.log("process.started", {runtimeMode: "reverse-gateway"})
+  await logger.close()
+  const name = (await readdir(directory)).find((entry) => entry.endsWith(".jsonl.zst"))
+  assert(name !== undefined)
+  const path = join(directory, name)
+  const bytes = await readFile(path)
+  bytes[bytes.length - 1] = /** @type {number} */ (bytes[bytes.length - 1]) ^ 0xff
+  await writeFile(path, bytes)
+
+  const result = await invoke("logs", "search", "--directory", directory, "--event", "process.started")
+  assert.equal(result.code, 2)
+  assert.equal(result.stdout, "")
+  assert.match(result.stderr, /Socketduct log evidence error/)
+})
+
+test("tail reader incrementally follows rotation and prunes retention-deleted cursors", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-logs-incremental-tail-"))
+  const directory = join(root, "logs")
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const logger = createCompressedJsonlFileLogger({directory, role: "reverse-hub", frameMaxBytes: 256, maxSegmentBytes: 1024, compressionLevel: 1})
+  await logger.flush()
+  for (let index = 0; index < 8; index += 1) {
+    logger.log("process.started", {runtimeMode: "reverse-hub"})
+    await logger.flush()
+  }
+  await logger.flush()
+
+  const reader = new CompressedLogTailReader(directory)
+  const initial = await reader.poll()
+  assert(initial.records.length > 0)
+  const identities = new Set(initial.records.map((record) => `${record.writerEpoch}\0${record.eventSequence}`))
+  assert.equal(identities.size, initial.records.length)
+  const decoded = reader.status().decodedFrames
+  assert(decoded > 0)
+  assert.deepEqual((await reader.poll()).records, [])
+  assert.equal(reader.status().decodedFrames, decoded)
+
+  logger.log("process.started", {runtimeMode: "reverse-hub"})
+  await logger.flush()
+  await logger.flush()
+  const activeDelta = await reader.poll()
+  assert(activeDelta.records.length > 0)
+  for (const record of activeDelta.records) assert.equal(identities.has(`${record.writerEpoch}\0${record.eventSequence}`), false)
+  await logger.close()
+  const closeDelta = await reader.poll()
+  assert(closeDelta.records.length > 0)
+  for (const record of closeDelta.records) assert.equal(identities.has(`${record.writerEpoch}\0${record.eventSequence}`), false)
+
+  const oldSegments = (await readdir(directory)).filter((name) => name.endsWith(".jsonl.zst"))
+  assert(oldSegments.length > 1, "fixture must rotate through more than one segment")
+  for (const name of oldSegments) await utimes(join(directory, name), new Date(1_000), new Date(1_000))
+  const later = createCompressedJsonlFileLogger({directory, role: "reverse-hub", compressionLevel: 1})
+  later.log("runtime.status", {virtualStreams: 2})
+  await later.close()
+  const laterSegments = (await readdir(directory)).filter((name) => name.endsWith(".jsonl.zst") && !oldSegments.includes(name))
+  for (const name of laterSegments) await utimes(join(directory, name), new Date(10_000), new Date(10_000))
+  const laterDelta = await reader.poll()
+  assert(laterDelta.records.some((record) => record.event === "runtime.status"))
+
+  await enforceLogRetention({directory, maxAgeMs: 5_000, maxBytes: 1_000_000, now: () => new Date(10_000)})
+  const beforePruneDecode = reader.status().decodedFrames
+  assert.deepEqual((await reader.poll()).records, [])
+  const survivingSegments = (await readdir(directory)).filter((name) => name.endsWith(".jsonl.zst")).length
+  assert(reader.status().trackedSegments <= survivingSegments)
+  assert.equal(reader.status().decodedFrames, beforePruneDecode)
+})
+
+/** @param {...string} args - CLI arguments. */
+async function invoke(...args) {
+  try {
+    const result = await run(process.execPath, [cli.pathname, ...args])
+    return {code: 0, stdout: result.stdout, stderr: result.stderr}
+  } catch (error) {
+    if (error === null || typeof error !== "object") throw error
+    return {
+      code: /** @type {{code?: number}} */ (error).code,
+      stdout: /** @type {{stdout?: string}} */ (error).stdout ?? "",
+      stderr: /** @type {{stderr?: string}} */ (error).stderr ?? ""
+    }
+  }
+}
+
+/** @param {() => boolean} predicate - Completion check. @param {import('node:child_process').ChildProcess} child - CLI process. @param {() => string} stderr - Error output. */
+async function waitFor(predicate, child, stderr) {
+  if (predicate()) return
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer
+  await new Promise((resolve, reject) => {
+    const cleanup = () => { if (timer !== undefined) clearTimeout(timer); child.stdout?.off("data", onData); child.off("exit", onExit) }
+    const onData = () => { if (predicate()) { cleanup(); resolve(undefined) } }
+    const onExit = (/** @type {number | null} */ code) => { cleanup(); reject(new Error(`CLI exited ${code}: ${stderr()}`)) }
+    timer = setTimeout(() => { cleanup(); reject(new Error(`Timed out waiting for CLI output: ${stderr()}`)) }, 5_000)
+    child.stdout?.on("data", onData)
+    child.once("exit", onExit)
+  })
+}

package/test/integration/logging-compressed-recovery.test.js

@@ -0,0 +1,186 @@
+/* eslint-disable jsdoc/escape-inline-tags, jsdoc/require-param-type, jsdoc/require-returns */
+import assert from "node:assert/strict"
+import {createHash, randomBytes} from "node:crypto"
+import {mkdtemp, readdir, rm, stat, utimes, writeFile} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+import test from "node:test"
+
+import {createLogBatchId, inspectLogBatch} from "../../src/logging/log-batch.js"
+import {readCompressedLogDirectory} from "../../src/logging/compressed-log-reader.js"
+import {CompressedLogWorkerSink} from "../../src/logging/compressed-log-worker.js"
+import {enforceLogRetention} from "../../src/logging/log-retention.js"
+import {createIndexEntry, createIndexHeader, INDEX_ENTRY_BYTES, INDEX_HEADER_BYTES, uuidBytes} from "../../src/logging/log-segment-index.js"
+import {compressLogFrame} from "../../src/logging/zstd-frame-codec.js"
+
+test("recovery indexes a complete data-synced orphan without duplicating its batch", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-orphan-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const fixture = await createRecoveryFixture(root, false)
+  const sink = new CompressedLogWorkerSink(fixture.options)
+  const recovered = await sink.start()
+  assert.equal(recovered.durableHighWater, "2")
+  assert.equal(recovered.orphanRecoveredCount, 1)
+  assert.equal(recovered.lastDurableBatch?.batchId, fixture.secondBatchId)
+  assert.equal((await stat(fixture.indexPath)).size, INDEX_HEADER_BYTES + 2 * INDEX_ENTRY_BYTES)
+
+  const duplicate = await sink.appendBatch(fixture.secondMessage)
+  assert.equal(duplicate.duplicate, true)
+  assert.equal((await stat(fixture.dataPath)).size, fixture.firstFrame.length + fixture.secondFrame.length)
+  await sink.close()
+  const result = await readCompressedLogDirectory(root)
+  assert.equal(result.incomplete, false)
+  assert.deepEqual(result.records.map((record) => record.eventSequence), ["1", "2"])
+})
+
+test("recovery truncates only a torn final data frame and accepts its replay", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-torn-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const fixture = await createRecoveryFixture(root, true)
+  const sink = new CompressedLogWorkerSink(fixture.options)
+  const recovered = await sink.start()
+  assert.equal(recovered.durableHighWater, "1")
+  assert.equal((await stat(fixture.dataPath)).size, fixture.firstFrame.length)
+
+  const replayed = await sink.appendBatch(fixture.secondMessage)
+  assert.equal(replayed.duplicate, false)
+  await sink.close()
+  const result = await readCompressedLogDirectory(root)
+  assert.equal(result.incomplete, false)
+  assert.deepEqual(result.records.map((record) => record.eventSequence), ["1", "2"])
+})
+
+test("worker acknowledgements retain only the latest durable batch identity", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-bounded-ack-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const writerEpoch = randomBytes(16)
+  const options = {directory: root, role: "reverse-hub", writerEpoch: writerEpoch.toString("base64url"), maxSegmentBytes: 4096, compressionLevel: 19}
+  const sink = new CompressedLogWorkerSink(options)
+  await sink.start()
+  let latest = await sink.appendBatch(batchMessage(writerEpoch, 1))
+  for (let sequence = 2; sequence <= 40; sequence += 1) latest = await sink.appendBatch(batchMessage(writerEpoch, sequence))
+  assert.equal(Object.hasOwn(latest, "durableBatchIds"), false)
+  assert.deepEqual(latest.lastDurableBatch, {
+    batchId: batchMessage(writerEpoch, 40).batchId,
+    firstSequence: "40",
+    lastSequence: "40"
+  })
+  assert.equal((await sink.appendBatch(batchMessage(writerEpoch, 40))).duplicate, true)
+  await sink.close()
+
+  const restarted = new CompressedLogWorkerSink(options)
+  const recovered = await restarted.start()
+  assert.equal(Object.hasOwn(recovered, "durableBatchIds"), false)
+  assert.deepEqual(recovered.lastDurableBatch, latest.lastDurableBatch)
+  await restarted.close()
+})
+
+test("recovery accepts a retention-deleted prefix but rejects interior gaps", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-compressed-retained-prefix-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const writerEpoch = randomBytes(16)
+  const options = {directory: root, role: "reverse-hub", writerEpoch: writerEpoch.toString("base64url"), maxSegmentBytes: 4096, compressionLevel: 19, retentionBytes: 1_000_000}
+
+  const segments = []
+  for (let sequence = 1; sequence <= 3; sequence += 1) {
+    const sink = new CompressedLogWorkerSink(options)
+    await sink.start()
+    await sink.appendBatch(batchMessage(writerEpoch, sequence))
+    segments.push(/** @type {string} */ (sink.status().segmentPath))
+    await sink.close()
+  }
+  assert.equal(segments.length, 3)
+  for (let index = 0; index < segments.length; index += 1) {
+    await utimes(/** @type {string} */ (segments[index]), new Date(1_000 + index), new Date(1_000 + index))
+  }
+  await enforceLogRetention({directory: root, maxAgeMs: 1, maxBytes: 1_000_000, now: () => new Date(1_003)})
+  assert.equal((await readdir(root)).filter((name) => name.endsWith(".jsonl.zst")).length, 1)
+
+  const recovered = new CompressedLogWorkerSink(options)
+  assert.equal((await recovered.start()).durableHighWater, "3")
+  assert.equal((await recovered.appendBatch(batchMessage(writerEpoch, 4))).durableHighWater, "4")
+  await recovered.close()
+
+  const gapDirectory = join(root, "interior-gap")
+  const gapEpoch = randomBytes(16)
+  const gapOptions = {...options, directory: gapDirectory, writerEpoch: gapEpoch.toString("base64url")}
+  const gapSegments = []
+  for (let sequence = 1; sequence <= 3; sequence += 1) {
+    const sink = new CompressedLogWorkerSink(gapOptions)
+    await sink.start()
+    await sink.appendBatch(batchMessage(gapEpoch, sequence))
+    gapSegments.push(/** @type {string} */ (sink.status().segmentPath))
+    await sink.close()
+  }
+  const missing = /** @type {string} */ (gapSegments[1])
+  await Promise.all([rm(missing), rm(`${missing}.idx`), rm(`${missing}.sealed`)])
+  await assert.rejects(() => new CompressedLogWorkerSink(gapOptions).start(), /interior sequence gap/)
+})
+
+/**
+ * @param {string} directory - Fixture directory. @param {boolean} torn - Whether to tear the orphan frame.
+ * @param torn
+ */
+async function createRecoveryFixture(directory, torn) {
+  const writerEpoch = randomBytes(16)
+  const writerEpochText = writerEpoch.toString("base64url")
+  const segmentUuidText = "123e4567-e89b-42d3-a456-426614174000"
+  const segmentUuid = uuidBytes(segmentUuidText)
+  const stem = `reverse-hub-${writerEpochText}-${segmentUuidText}.jsonl.zst`
+  const dataPath = join(directory, stem)
+  const indexPath = `${dataPath}.idx`
+  const firstRaw = record(writerEpochText, 1, "process.started")
+  const secondRaw = record(writerEpochText, 2, "runtime.status")
+  const firstFrame = await compressLogFrame(firstRaw)
+  const secondFrame = await compressLogFrame(secondRaw)
+  const first = inspectLogBatch(firstRaw, writerEpoch)
+  const firstEntry = createIndexEntry({
+    segmentUuid,
+    writerEpoch,
+    batchId: first.batchId,
+    firstSequence: first.firstSequence,
+    lastSequence: first.lastSequence,
+    dataOffset: 0n,
+    compressedLength: BigInt(firstFrame.length),
+    uncompressedLength: BigInt(firstRaw.length),
+    recordCount: 1,
+    minTimestamp: first.minTimestamp,
+    maxTimestamp: first.maxTimestamp,
+    frameSha256: createHash("sha256").update(firstFrame).digest()
+  })
+  await writeFile(dataPath, Buffer.concat([firstFrame, torn ? secondFrame.subarray(0, secondFrame.length - 3) : secondFrame]), {mode: 0o600})
+  await writeFile(indexPath, Buffer.concat([createIndexHeader({segmentUuid, writerEpoch}), firstEntry]), {mode: 0o600})
+  const secondBatchId = createLogBatchId(writerEpoch, 2n, 2n, secondRaw).toString("base64url")
+  return {
+    options: {directory, role: "reverse-hub", writerEpoch: writerEpochText, maxSegmentBytes: 4096, compressionLevel: 19},
+    dataPath,
+    indexPath,
+    firstFrame,
+    secondFrame,
+    secondBatchId,
+    secondMessage: {batchId: secondBatchId, firstSequence: "2", lastSequence: "2", jsonl: secondRaw}
+  }
+}
+
+/**
+ * @param {string} writerEpoch - Epoch. @param {number} sequence - Event sequence. @param {string} event - Event name.
+ * @param sequence
+ * @param event
+ */
+function record(writerEpoch, sequence, event) {
+  return Buffer.from(`${JSON.stringify({timestamp: new Date(1_795_000_000_000 + sequence).toISOString(), event, processId: 1, role: "reverse-hub", writerEpoch, eventSequence: String(sequence)})}\n`)
+}
+
+/**
+ * @param {Buffer} writerEpoch - Epoch.
+ * @param {number} sequence - Event sequence.
+ */
+function batchMessage(writerEpoch, sequence) {
+  const jsonl = record(writerEpoch.toString("base64url"), sequence, "runtime.status")
+  return {
+    batchId: createLogBatchId(writerEpoch, BigInt(sequence), BigInt(sequence), jsonl).toString("base64url"),
+    firstSequence: String(sequence),
+    lastSequence: String(sequence),
+    jsonl
+  }
+}

package/test/integration/reverse-gateway.test.js

@@ -307,6 +307,45 @@ test("reverse client contains a TLS AUTH write race inside the transport", async
   await assert.rejects(connecting, /closed/i)
 })
 
+test("fatal hub GOAWAY preserves validated attribution on the public client error", async (t) => {
+  /** @type {AuthWriteSocket | undefined} */
+  let physical
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "fatal_goaway_attribution_client",
+    hub: {host: "127.0.0.1", port: 3100, token: "client-token"},
+    tls: {servername: "localhost"},
+    continuousReconnect: false,
+    createPhysicalSocket: () => {
+      physical = new AuthWriteSocket()
+      return /** @type {import('node:tls').TLSSocket} */ (/** @type {unknown} */ (physical))
+    }
+  })
+  t.after(() => client.close())
+  const connecting = client.connect()
+  physical?.emit("secureConnect")
+  physical?.emit("data", encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({
+    code: "PROTOCOL_VIOLATION",
+    disconnectIncidentId: "AAAAAAAAAAAAAAAAAAAAAA",
+    disconnectReason: "protocol_violation",
+    incidentOrigin: "reverse_hub",
+    physicalRole: "client",
+    clientConnectionGeneration: 1,
+    fanOutCount: 0,
+    resumeSuccessCount: 0,
+    terminalStreamCount: 0
+  })))
+  /** @type {Error & Record<string, unknown> | undefined} */
+  let rejection
+  await assert.rejects(withTimeout(connecting, "fatal attributed GOAWAY"), (error) => {
+    rejection = /** @type {Error & Record<string, unknown>} */ (error)
+    return rejection.code === "PROTOCOL_VIOLATION"
+  })
+  assert.equal(rejection?.disconnectIncidentId, "AAAAAAAAAAAAAAAAAAAAAA")
+  assert.equal(rejection?.disconnectReason, "protocol_violation")
+  assert.equal(rejection?.incidentOrigin, "reverse_hub")
+})
+
 test("recovered reverse clients require explicit cold durable identity before any physical attempt", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-recovery-contract-"))
   t.after(() => rm(root, {recursive: true, force: true}))
@@ -2168,6 +2207,143 @@ test("an expired reverse resume window fails the logical stream once and release
   assert.equal(targets[0]?.destroyed, true)
 })
 
+test("one gateway disconnect incident preserves physical cause across fan-out and terminal resume errors", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-attribution-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-attribution-token"}, {username: "app", token: "client-attribution-token"}])
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const hubEvents = []
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const gatewayEvents = []
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const clientEvents = []
+  const hub = await startReverseGatewayHub({
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    authorizeGateway: () => true,
+    authorizeClientGateway: () => true,
+    authorizeOpen: () => true,
+    resumeWindowMs: 40,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { hubEvents.push({event, ...fields}) }},
+    connectionFingerprint: {key: Buffer.alloc(32, 0x5a), keyEpoch: "test-epoch"}
+  })
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const targets = []
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "low_entropy_gateway_connection",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-attribution-token"},
+    tls,
+    authorizeTarget: () => true,
+    reconnectDelayMs: 150,
+    maxReconnectDelayMs: 150,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { gatewayEvents.push({event, ...fields}) }},
+    createTargetConnection: () => {
+      const target = new InterruptibleTarget()
+      targets.push(target)
+      return /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (target))
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({
+    gatewayId: "o2",
+    connectionId: "low_entropy_client_connection",
+    hub: {host: "127.0.0.1", port: hub.port, token: "client-attribution-token"},
+    tls,
+    reconnectDelayMs: 5,
+    maxReconnectDelayMs: 10,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { clientEvents.push({event, ...fields}) }}
+  })
+  t.after(() => client.close())
+  await client.connect()
+  const sockets = [client.createConnection({host: "target", port: 2375}), client.createConnection({host: "target", port: 2375})]
+  await Promise.all(sockets.map((socket) => onceEvent(socket, "connect")))
+  const terminalErrors = sockets.map((socket) => nextError(socket))
+
+  await hub.closeActiveGateway("o2")
+  const errors = /** @type {Array<Error & Record<string, unknown>>} */ (await Promise.all(terminalErrors))
+  assert.deepEqual(errors.map((error) => error.code), ["RESUME_WINDOW_EXPIRED", "RESUME_WINDOW_EXPIRED"])
+  assert.equal(new Set(errors.map((error) => error.disconnectIncidentId)).size, 1)
+  for (const error of errors) {
+    assert.match(/** @type {string} */ (error.disconnectIncidentId), /^[A-Za-z0-9_-]{22}$/)
+    assert.equal(error.disconnectReason, "unknown_transport_close")
+    assert.equal(error.incidentOrigin, "reverse_hub")
+    assert.equal(error.physicalRole, "gateway")
+    assert.equal(typeof error.clientConnectionGeneration, "number")
+    assert.equal(typeof error.gatewayConnectionGeneration, "number")
+    assert.equal(error.fanOutCount, 2)
+  }
+  const detached = hubEvents.find(({event, physicalRole}) => event === "reverse_hub.physical_detached" && physicalRole === "gateway")
+  assert(detached !== undefined)
+  assert.equal(detached.disconnectIncidentId, /** @type {Error & Record<string, unknown>} */ (errors[0]).disconnectIncidentId)
+  assert.match(/** @type {string} */ (detached.connectionFingerprint), /^[a-f0-9]{32}$/)
+  assert.equal(detached.fingerprintKeyEpoch, "test-epoch")
+  assert(hubEvents.some(({event, fanOutCount}) => event === "reverse_hub.streams_interrupted" && fanOutCount === 2))
+  assert(hubEvents.some(({event, terminalStreamCount}) => event === "reverse_hub.streams_reset" && terminalStreamCount === 2))
+  assert(clientEvents.some(({event}) => event === "reverse_client.physical_detached"))
+  assert(gatewayEvents.some(({event}) => event === "reverse_gateway.physical_detached"))
+  assert.equal(targets.length, 2)
+  assert.doesNotMatch(JSON.stringify([hubEvents, gatewayEvents, clientEvents]), /low_entropy_(?:gateway|client)_connection|attribution-token/)
+})
+
+test("peer GOAWAY classification and hub attribution reach terminal non-resumable RESET", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-terminal-attribution-"))
+  t.after(() => rm(root, {recursive: true, force: true}))
+  const certificates = generateTestCertificates(root)
+  const tokens = new StaticTokenStore([{username: "home", token: "gateway-token"}, {username: "app", token: "client-token"}])
+  /** @type {Array<Record<string, unknown> & {event: string}>} */
+  const hubEvents = []
+  const hub = await startReverseGatewayHub({
+    tokens,
+    tls: {certFile: certificates.serverCertFile, keyFile: certificates.serverKeyFile},
+    authorizeGateway: () => true,
+    authorizeClientGateway: () => true,
+    authorizeOpen: () => true,
+    logger: {log: (/** @type {string} */ event, /** @type {Record<string, unknown>} */ fields = {}) => { hubEvents.push({event, ...fields}) }}
+  })
+  t.after(() => hub.close())
+  const tls = {caFile: certificates.caCertFile, servername: "localhost"}
+  const gateway = new OutboundReverseGateway({
+    gatewayId: "o2",
+    connectionId: "terminal_attribution_gateway",
+    hub: {host: "127.0.0.1", port: hub.port, token: "gateway-token"},
+    tls,
+    authorizeTarget: () => true,
+    createTargetConnection: () => /** @type {import('node:net').Socket} */ (/** @type {unknown} */ (new InterruptibleTarget())),
+    createPhysicalSocket: (options) => {
+      const physical = connectTls({host: options.host, port: options.port, ...options.tls})
+      const originalWrite = physical.write.bind(physical)
+      physical.write = /** @type {typeof physical.write} */ ((chunk, ...args) => {
+        if (!Buffer.isBuffer(chunk) || chunk[5] !== V3FrameType.GOAWAY) return Reflect.apply(originalWrite, physical, [chunk, ...args])
+        const safeGoaway = encodeV3Frame({type: V3FrameType.GOAWAY, streamId: 0, sequence: 0}, encodeV3Control({code: "GATEWAY_MAINTENANCE", disconnectIncidentId: "BBBBBBBBBBBBBBBBBBBBBB"}))
+        return Reflect.apply(originalWrite, physical, [safeGoaway, ...args])
+      })
+      return physical
+    }
+  })
+  t.after(() => gateway.close())
+  await gateway.start()
+  const client = new ReverseGatewayConnection({gatewayId: "o2", connectionId: "terminal_attribution_client", hub: {host: "127.0.0.1", port: hub.port, token: "client-token"}, tls, continuousReconnect: false})
+  t.after(() => client.close())
+  await client.connect()
+  const socket = client.createConnection({host: "target", port: 2375})
+  await onceEvent(socket, "connect")
+  const terminal = nextError(socket)
+  await gateway.close()
+  const error = /** @type {Error & Record<string, unknown>} */ (await withTimeout(terminal, "terminal peer GOAWAY reset"))
+  assert.equal(error.code, "GATEWAY_MAINTENANCE")
+  assert.equal(error.disconnectReason, "peer_goaway")
+  assert.equal(error.incidentOrigin, "reverse_hub")
+  assert.equal(error.physicalRole, "gateway")
+  assert.equal(error.fanOutCount, 1)
+  assert.equal(error.terminalStreamCount, 1)
+  assert.notEqual(error.disconnectIncidentId, "BBBBBBBBBBBBBBBBBBBBBB")
+  assert(hubEvents.some(({event, terminalStreamCount}) => event === "reverse_hub.streams_reset" && terminalStreamCount === 1), JSON.stringify(hubEvents))
+})
+
 test("reverse mode enforces verified TLS and stream resource bounds", async (t) => {
   const root = await mkdtemp(join(tmpdir(), "socketduct-reverse-limits-"))
   const wrongRoot = await mkdtemp(join(tmpdir(), "socketduct-reverse-wrong-ca-"))

package/test/integration/reverse-route-class.test.js

@@ -364,7 +364,12 @@ test("a backpressured gateway does not block DATA or a new OPEN for another rout
     t.after(() => socket.destroy())
     return nextError(socket)
   })
-  assert.equal((await withTimeout(streamAError, "gateway A output limit")).code, "OUTPUT_BACKPRESSURE_LIMIT")
+  const outputError = /** @type {Error & Record<string, unknown>} */ (await withTimeout(streamAError, "gateway A output limit"))
+  assert.equal(outputError.code, "OUTPUT_BACKPRESSURE_LIMIT")
+  assert.equal(outputError.disconnectReason, "output_backpressure_limit")
+  assert.equal(outputError.incidentOrigin, "reverse_hub")
+  assert.equal(outputError.physicalRole, "gateway")
+  assert.match(/** @type {string} */ (outputError.disconnectIncidentId), /^[A-Za-z0-9_-]{22}$/)
   await withTimeout(Promise.all(queuedAErrors), "queued gateway A stream cleanup")
   assert.equal(await exchange(streamB, "after-limit"), "b:after-limit")
   assert.equal(hub.status().healthyGateways, 1)

package/test/unit/config/docker-gateway-files.test.js

@@ -36,6 +36,8 @@ test("TensorBuzz exclusively owns verification and container build validation",
   const packageMetadata = JSON.parse(packageJson)
 
   assert.deepEqual(workflowNames, [])
+  assert.match(tensorbuzz, /^dependency_roots:\n {2}- path: \.$/m)
+  assert.doesNotMatch(tensorbuzz, /^\s*- npm ci$/m)
   assert.match(tensorbuzz, /DOCKER_HOST: "tcp:\/\/docker_server:2375"/)
   assert.match(tensorbuzz, /docker_server:\n\s+image: "docker:[^"]+-dind"/)
   assert.match(tensorbuzz, /privileged: true/)

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", () => {