socketduct 0.1.15

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

@@ -0,0 +1,674 @@
+import {createMockScope, describe, expect, it, withTestCleanup} from "@velocious/testing"
+import {chmod, mkdtemp, mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile} from "node:fs/promises"
+import {tmpdir} from "node:os"
+import {join} from "node:path"
+
+import {createJsonlFileLogger, createStructuredLogger, errorDiagnostics, logDiagnostic} from "../../../src/logging/structured-logger.js"
+
+const FIXED_TIME = "2026-09-05T12:34:56.789Z"
+
+/** @param {string} root - Temporary directory. */
+async function cleanup(root) {
+  await rm(root, {recursive: true, force: true})
+}
+
+/**
+ * @param {string} contents - JSONL.
+ * @returns {Array<Record<string, unknown>>} Parsed entries.
+ */
+function parseLines(contents) {
+  return contents.trim().split("\n").filter(Boolean).map((line) => JSON.parse(line))
+}
+
+describe("structured logger", {timeoutMs: 15000}, () => {
+  it("structured logger writes one allowlisted bounded JSON object per line", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({
+      role: "tensorbuzz-client",
+      processId: 4242,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line)
+    })
+
+    logger.log("transport.connected", {
+      generation: 7,
+      gatewayId: "g".repeat(100),
+      reconnect: true,
+      token: "lowentropysecret",
+      password: "alphabeticsecret",
+      authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.private.signature",
+      url: "https://user:secret@example.test/private",
+      target: {host: "private.internal", port: 2375},
+      error: new Error("lowentropysecret eyJhbGciOiJIUzI1NiJ9.private.signature")
+    })
+
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    expect(line.endsWith("\n")).toBe(true)
+    const entry = JSON.parse(line)
+    expect(entry).toEqual({
+      timestamp: FIXED_TIME,
+      event: "transport.connected",
+      processId: 4242,
+      role: "tensorbuzz-client",
+      generation: 7,
+      gatewayId: "g".repeat(64),
+      reconnect: true
+    })
+    expect(Buffer.byteLength(line) <= 1024).toBeTruthy()
+    const serialized = lines.join("")
+    expect(serialized).not.toMatch(/lowentropysecret|alphabeticsecret|eyJhbGci|private\.internal|example\.test|2375/)
+  })
+
+  it("structured logger rejects unknown events and maps untrusted error codes to a safe classification", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({
+      role: "embedded-client",
+      processId: 5,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line)
+    })
+
+    logger.log("attacker.lowentropysecret", {errorCode: "ECONNRESET"})
+    logger.log("virtual_stream.error", {
+      streamId: 9,
+      errorCode: "eyJhbGciOiJIUzI1NiJ9.private.signature",
+      errorMessage: "alphabeticsecret",
+      stack: "lowentropysecret"
+    })
+
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    expect(JSON.parse(line)).toEqual({
+      timestamp: FIXED_TIME,
+      event: "virtual_stream.error",
+      processId: 5,
+      role: "embedded-client",
+      streamId: 9,
+      errorCode: "UNKNOWN",
+      errorClass: "unknown"
+    })
+    expect(line).not.toMatch(/eyJhbGci|alphabeticsecret|lowentropysecret/)
+    const hostileError = new Proxy({}, {get: () => { throw new Error("alphabeticsecret") }})
+    expect(errorDiagnostics(hostileError)).toEqual({errorCode: "UNKNOWN", errorClass: "unknown"})
+  })
+
+  it("retains actionable error details for virtual stream failures", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({
+      role: "embedded-client",
+      processId: 6,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line)
+    })
+    const error = Object.assign(new Error("Remote Docker socket closed unexpectedly"), {code: "ECONNRESET"})
+
+    logDiagnostic(logger, "virtual_stream.error", {streamId: 10, ...errorDiagnostics(error)})
+
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    const entry = JSON.parse(line)
+    expect(entry.errorCode).toBe("ECONNRESET")
+    expect(entry.errorClass).toBe("network")
+    expect(entry.errorName).toBe("Error")
+    expect(entry.errorMessage).toBe("Remote Docker socket closed unexpectedly")
+    expect(entry.errorStack).toMatch(/Remote Docker socket closed unexpectedly/)
+  })
+
+  it("preserves bounded failure classifications when error details exceed the JSONL limit", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({
+      role: "embedded-client",
+      processId: 7,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line)
+    })
+    const error = Object.assign(new Error("Connection reset ".repeat(200)), {code: "ECONNRESET"})
+
+    logDiagnostic(logger, "virtual_stream.error", {streamId: 11, ...errorDiagnostics(error)})
+
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    const entry = JSON.parse(line)
+    expect(Buffer.byteLength(line) <= 1024).toBeTruthy()
+    expect(entry.errorCode).toBe("ECONNRESET")
+    expect(entry.errorClass).toBe("network")
+    expect(entry.streamId).toBe(11)
+    expect(entry.errorMessage).toMatch(/^Connection reset/)
+    expect(entry.errorStack).toBeUndefined()
+  })
+
+  it("redacts credentials while retaining actionable error details", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({
+      role: "embedded-client",
+      processId: 8,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line)
+    })
+    const error = Object.assign(new Error("Target https://credential-user:credential-secret@example.test rejected Bearer abc.def password=another-secret"), {code: "ECONNREFUSED"})
+
+    logDiagnostic(logger, "virtual_stream.error", {streamId: 13, ...errorDiagnostics(error)})
+
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    expect(line).toMatch(/Target https:\/\/\[REDACTED\]@example\.test rejected Bearer \[REDACTED\] password=\[REDACTED\]/)
+    expect(line).not.toMatch(/credential-user|credential-secret|abc\.def|another-secret/)
+  })
+
+  it("passes actionable error details to custom loggers", () => {
+    /** @type {Record<string, unknown>[]} */
+    const fields = []
+    /** @type {{log(event: string, fields?: Record<string, unknown>): void}} */
+    const logger = {
+      log(_event, eventFields = {}) {
+        fields.push(eventFields)
+      }
+    }
+    const error = Object.assign(new Error("Remote Docker socket closed unexpectedly"), {code: "ECONNRESET"})
+
+    logDiagnostic(logger, "virtual_stream.error", {
+      streamId: 12,
+      ...errorDiagnostics(error)
+    })
+
+    expect(fields.length).toBe(1)
+    const eventFields = fields[0]
+    if (eventFields === undefined) throw new Error("Expected captured diagnostic fields")
+    expect(eventFields.errorCode).toBe("ECONNRESET")
+    expect(eventFields.errorClass).toBe("network")
+    expect(eventFields.errorName).toBe("Error")
+    expect(eventFields.errorMessage).toBe("Remote Docker socket closed unexpectedly")
+    expect(eventFields.errorStack).toMatch(/Remote Docker socket closed unexpectedly/)
+  })
+
+  it("structured logger snapshots identity and writer options and fixes its failure classification", () => {
+    /** @type {string[]} */
+    const lines = []
+    /** @type {string[]} */
+    const replacedLines = []
+    /** @type {string[]} */
+    const reports = []
+    const options = {
+      role: "embedded-client",
+      processId: 44,
+      now: () => new Date(FIXED_TIME),
+      writeLine: (/** @type {string} */ line) => lines.push(line),
+      stderr: {write: (/** @type {string} */ message) => { reports.push(message); return true }},
+      failureCode: "alphabeticsecret"
+    }
+    const logger = createStructuredLogger(options)
+    options.role = "mutated-secret"
+    options.now = () => new Date("2040-01-01T00:00:00.000Z")
+    options.writeLine = (line) => replacedLines.push(line)
+    options.failureCode = "lowentropysecret"
+
+    logger.log("process.started", {runtimeMode: "summary"})
+    expect(lines.length).toBe(1)
+    expect(replacedLines.length).toBe(0)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    expect(JSON.parse(line)).toEqual({
+      timestamp: FIXED_TIME,
+      event: "process.started",
+      processId: 44,
+      role: "embedded-client",
+      runtimeMode: "summary"
+    })
+
+    const failingOptions = {
+      role: "embedded-client",
+      writeLine: () => { throw new Error("alphabeticsecret") },
+      stderr: options.stderr,
+      failureCode: "lowentropysecret"
+    }
+    createStructuredLogger(failingOptions).log("process.started", {runtimeMode: "summary"})
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_WRITER_ERROR)\n"])
+  })
+
+  it("file logger appends valid owner-only JSONL across logger instances", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-append-"))
+    after(() => cleanup(root))
+    const options = {directory: root, role: "reverse-hub", processId: 101, now: () => new Date(FIXED_TIME)}
+
+    createJsonlFileLogger(options).log("process.started", {runtimeMode: "reverse-hub"})
+    createJsonlFileLogger(options).log("runtime.status", {physicalConnections: 2, virtualStreams: 3})
+
+    const path = join(root, "reverse-hub-101.jsonl")
+    const contents = await readFile(path, "utf8")
+    expect(parseLines(contents).map(({event}) => event)).toEqual(["process.started", "runtime.status"])
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+  }))
+
+  describe("file logger preserves an incomplete tail before same or fresh instance appends", () => {
+    for (const maxFiles of [2, 5]) {
+      for (const freshInstance of [false, true]) {
+        it(`maxFiles=${maxFiles}, freshInstance=${freshInstance}`, async () => withTestCleanup(async (after) => {
+          const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-tail-"))
+          after(() => cleanup(root))
+          const options = {directory: root, role: "relay", processId: 101, maxFiles, maxFileBytes: 1024, now: () => new Date(FIXED_TIME)}
+          const logger = createJsonlFileLogger(options)
+          logger.log("process.started", {runtimeMode: "relay"})
+          const active = join(root, "relay-101.jsonl")
+          await writeFile(active, '{"timestamp":"2026-', {flag: "a"})
+          const torn = await readFile(active)
+
+          const resumed = freshInstance ? createJsonlFileLogger(options) : logger
+          resumed.log("transport.connected", {generation: 1})
+          resumed.log("runtime.status", {physicalConnections: 1})
+
+          expect((await readdir(root)).sort()).toEqual(["relay-101.jsonl", "relay-101.jsonl.1"])
+          expect((await readFile(`${active}.1`)).equals(torn)).toBeTrue()
+          const contents = await readFile(active, "utf8")
+          expect(contents.endsWith("\n")).toBeTruthy()
+          expect(parseLines(contents).map(({event}) => event)).toEqual(["transport.connected", "runtime.status"])
+          for (const path of [active, `${active}.1`]) {
+            const stats = await stat(path)
+            expect(stats.size <= 1024).toBeTruthy()
+            expect(stats.mode & 0o777).toBe(0o600)
+          }
+        }))
+      }
+    }
+  })
+
+  it("file logger preserves an incomplete tail and pauses with maxFiles one", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-tail-single-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-101.jsonl")
+    const torn = Buffer.from('{"event":"process.started"}\n{"timestamp":"2026-')
+    await writeFile(active, torn, {mode: 0o600})
+    /** @type {string[]} */
+    const reports = []
+    const logger = createJsonlFileLogger({
+      directory: root,
+      role: "relay",
+      processId: 101,
+      maxFiles: 1,
+      maxFileBytes: 1024,
+      stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+    })
+
+    for (let generation = 1; generation <= 3; generation += 1) {
+      await expect(() => logger.log("transport.connected", {generation})).not.toThrow()
+    }
+
+    expect((await readFile(active)).equals(torn)).toBeTrue()
+    expect(await readdir(root)).toEqual(["relay-101.jsonl"])
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+  }))
+
+  it("file logger preserves an oversized incomplete tail before startup pruning", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-tail-pruning-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-101.jsonl")
+    const torn = Buffer.from(`${"{}\n".repeat(342)}{"timestamp":"2026-`)
+    await writeFile(active, torn, {mode: 0o600})
+    /** @type {string[]} */
+    const reports = []
+    const logger = createJsonlFileLogger({
+      directory: root,
+      role: "relay",
+      processId: 101,
+      maxFiles: 2,
+      maxFileBytes: 1024,
+      stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+    })
+
+    logger.log("process.started", {runtimeMode: "relay"})
+    logger.log("runtime.status", {physicalConnections: 1})
+
+    expect((await readFile(active)).equals(torn)).toBeTrue()
+    expect(await readdir(root)).toEqual(["relay-101.jsonl"])
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+  }))
+
+  describe("file logger pauses incomplete-tail recovery on real permission or rotation failures", () => {
+    for (const failure of ["unreadable-file", "unsafe-file-mode", "unwritable-directory", "unsafe-directory-mode", "blocked-retention"]) {
+      it(failure, async () => withTestCleanup(async (after) => {
+        const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-tail-failure-"))
+        const active = join(root, "relay-101.jsonl")
+        after(async () => {
+          await chmod(root, 0o700)
+          await cleanup(root)
+        })
+        const torn = Buffer.from('{}\n{"timestamp":"2026-')
+        await writeFile(active, torn, {mode: 0o600})
+        if (failure === "unreadable-file") await chmod(active, 0o200)
+        if (failure === "unsafe-file-mode") await chmod(active, 0o644)
+        if (failure === "unwritable-directory") await chmod(root, 0o500)
+        if (failure === "unsafe-directory-mode") await chmod(root, 0o755)
+        if (failure === "blocked-retention") {
+          await mkdir(`${active}.1`)
+          await writeFile(join(`${active}.1`, "blocker"), "fixture")
+        }
+        if (failure === "unwritable-directory") {
+          await expect(rename(active, `${active}.1`)).rejects.toMatchObject({code: "EACCES"})
+          await expect(writeFile(join(root, "create-probe"), "fixture", {flag: "wx"})).rejects.toMatchObject({code: "EACCES"})
+        }
+        /** @type {string[]} */
+        const reports = []
+        const logger = createJsonlFileLogger({
+          directory: root, role: "relay", processId: 101, maxFiles: 2,
+          stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+        })
+        for (let generation = 0; generation < 3; generation += 1) {
+          await expect(() => logger.log("transport.connected", {generation})).not.toThrow()
+        }
+        await chmod(root, 0o700)
+        await chmod(active, 0o600)
+        expect((await readFile(active)).equals(torn)).toBeTruthy()
+        expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+        if (failure === "blocked-retention") await rm(`${active}.1`, {recursive: true})
+
+        logger.log("transport.connected", {generation: 3})
+        expect((await readFile(`${active}.1`)).equals(torn)).toBeTruthy()
+        expect(parseLines(await readFile(active, "utf8")).map(({generation}) => generation)).toEqual([3])
+        expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+      }))
+    }
+  })
+
+  it("file logger preserves retained evidence when clean active creation is blocked", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-create-failure-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-101.jsonl")
+    const torn = Buffer.from('{}\n{"timestamp":"2026-')
+    await writeFile(`${active}.1`, torn, {mode: 0o600})
+    await mkdir(active, {mode: 0o700})
+    await expect(writeFile(active, "fixture", {flag: "a"})).rejects.toMatchObject({code: "EISDIR"})
+    /** @type {string[]} */
+    const reports = []
+    const logger = createJsonlFileLogger({
+      directory: root, role: "relay", processId: 101, maxFiles: 2,
+      stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+    })
+    for (let generation = 0; generation < 3; generation += 1) logger.log("transport.connected", {generation})
+    expect((await readFile(`${active}.1`)).equals(torn)).toBeTruthy()
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+    await rm(active, {recursive: true})
+    logger.log("transport.connected", {generation: 3})
+    expect((await readFile(`${active}.1`)).equals(torn)).toBeTruthy()
+    expect(parseLines(await readFile(active, "utf8")).map(({generation}) => generation)).toEqual([3])
+  }))
+
+  it("file logger verifies the mode of a newly created active file before writing", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-create-mode-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-101.jsonl")
+    /** @type {string[]} */
+    const reports = []
+    const logger = createJsonlFileLogger({
+      directory: root, role: "relay", processId: 101,
+      stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+    })
+    const previousMask = process.umask(0o777)
+    try {
+      logger.log("process.started", {runtimeMode: "relay"})
+    } finally {
+      process.umask(previousMask)
+    }
+    expect((await stat(active)).mode & 0o777).toBe(0)
+    expect((await stat(active)).size).toBe(0)
+    expect(reports).toEqual(["Socketduct logger failure (LOGGER_IO_ERROR)\n"])
+    await chmod(active, 0o600)
+    logger.log("transport.connected", {generation: 1})
+    expect(parseLines(await readFile(active, "utf8")).map(({event}) => event)).toEqual(["transport.connected"])
+  }))
+
+  describe("repeated incomplete tails respect numbered retention at the minimum size limit", () => {
+    for (const maxFiles of [1, 2, 5]) {
+      it(`maxFiles=${maxFiles}`, async () => withTestCleanup(async (after) => {
+        const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-tail-caps-"))
+        after(() => cleanup(root))
+        const active = join(root, "relay-101.jsonl")
+        /** @type {string[]} */
+        const reports = []
+        const logger = createJsonlFileLogger({
+          directory: root, role: "relay", processId: 101, maxFiles, maxFileBytes: 1024,
+          stderr: {write: (/** @type {string} */ message) => reports.push(message)}
+        })
+        logger.log("process.started", {runtimeMode: "relay"})
+        for (let generation = 1; generation <= (maxFiles === 1 ? 1 : 8); generation += 1) {
+          const size = (await stat(active)).size
+          await writeFile(active, "{".padEnd(1000 - size, "x"), {flag: "a"})
+          const torn = await readFile(active)
+          for (let attempt = 0; attempt < 3; attempt += 1) logger.log("transport.connected", {generation})
+          expect((await readFile(maxFiles === 1 ? active : `${active}.1`)).equals(torn)).toBeTruthy()
+          const files = await readdir(root)
+          expect(files.length).toBe(Math.min(generation + 1, maxFiles))
+          for (const file of files) expect((await stat(join(root, file))).size <= 1024).toBeTruthy()
+          if (maxFiles > 1) expect(parseLines(await readFile(active, "utf8")).map((entry) => entry.generation)).toEqual([generation, generation, generation])
+        }
+        expect(reports).toEqual(maxFiles === 1 ? ["Socketduct logger failure (LOGGER_IO_ERROR)\n"] : [])
+      }))
+    }
+  })
+
+  it("oversized sanitized records fall back to a bounded envelope", () => {
+    /** @type {string[]} */
+    const lines = []
+    const logger = createStructuredLogger({role: "relay", writeLine: (line) => lines.push(line)})
+    const counters = Object.fromEntries("activeTargets activeTunnels attachedSessions authenticatedConnections bufferedBytes bufferedTargetBytes clientPhysicalConnections connectionGeneration connectionIdentities controlQueuedBytes dataQueuedBytes detachedSessions gatewayPhysicalConnections gatewayRegistrations healthyGateways openFailures pendingOpens physicalAccepts physicalConnections physicalConnects rawDataBytes registeredGateways rejectedOpens rejectedRegistrations retainedClientIdentities targetOpens virtualStreams wireDataBytes".split(" ").map((field) => [field, Number.MAX_SAFE_INTEGER]))
+    logger.log("runtime.status", {...counters, password: "private-fixture-password"})
+    expect(lines.length).toBe(1)
+    const line = lines[0]
+    if (line === undefined) throw new Error("Expected a captured log record")
+    expect(Buffer.byteLength(line) <= 1024).toBeTruthy()
+    expect(Object.keys(JSON.parse(line))).toEqual(["timestamp", "event", "processId", "role"])
+    expect(line).not.toMatch(/private-fixture-password/)
+  })
+
+  it("file logger leaves newline-terminated historical corruption unchanged", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-historical-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-101.jsonl")
+    const historical = '{"timestamp":"torn{"timestamp":"joined"}\n'
+    await writeFile(active, historical, {mode: 0o600})
+    createJsonlFileLogger({directory: root, role: "relay", processId: 101}).log("transport.connected", {generation: 1})
+    const contents = await readFile(active, "utf8")
+    expect(contents.slice(0, historical.length)).toBe(historical)
+    expect(JSON.parse(contents.slice(historical.length)).event).toBe("transport.connected")
+    expect(await readdir(root)).toEqual(["relay-101.jsonl"])
+  }))
+
+  it("file logger rotates deterministically and bounds total retained files", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-rotate-"))
+    after(() => cleanup(root))
+    const logger = createJsonlFileLogger({
+      directory: root,
+      role: "relay",
+      processId: 202,
+      maxFileBytes: 1024,
+      maxFiles: 3,
+      now: () => new Date(FIXED_TIME)
+    })
+
+    for (let index = 0; index < 40; index += 1) {
+      logger.log("runtime.status", {
+        physicalConnections: index,
+        authenticatedConnections: index,
+        virtualStreams: index,
+        queuedBytes: index * 10,
+        bufferedBytes: index * 20
+      })
+    }
+
+    const files = (await readdir(root)).sort()
+    expect(files).toEqual(["relay-202.jsonl", "relay-202.jsonl.1", "relay-202.jsonl.2"])
+    for (const file of files) {
+      const path = join(root, file)
+      expect((await stat(path)).size <= 1024).toBeTruthy()
+      for (const entry of parseLines(await readFile(path, "utf8"))) expect(typeof entry.event).toBe("string")
+    }
+  }))
+
+  it("file logger enforces lower bounds after retention configuration changes", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-reconfigure-"))
+    after(() => cleanup(root))
+    const active = join(root, "relay-303.jsonl")
+    await writeFile(active, "{}\n".repeat(330), {mode: 0o600})
+    await writeFile(`${active}.1`, "{}\n".repeat(400), {mode: 0o600})
+    await writeFile(`${active}.2`, "{}\n", {mode: 0o600})
+    await writeFile(`${active}.9`, "{}\n", {mode: 0o600})
+
+    const logger = createJsonlFileLogger({directory: root, role: "relay", processId: 303, maxFileBytes: 1024, maxFiles: 2})
+    logger.log("process.started", {runtimeMode: "relay"})
+
+    const files = (await readdir(root)).sort()
+    expect(files).toEqual(["relay-303.jsonl", "relay-303.jsonl.1"])
+    for (const file of files) expect((await stat(join(root, file))).size <= 1024).toBeTruthy()
+  }))
+
+  it("file logger isolates active paths by role and process", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-paths-"))
+    after(() => cleanup(root))
+
+    createJsonlFileLogger({directory: root, role: "reverse-hub", processId: 10}).log("process.started", {runtimeMode: "reverse-hub"})
+    createJsonlFileLogger({directory: root, role: "reverse-gateway", processId: 10}).log("process.started", {runtimeMode: "reverse-gateway"})
+    createJsonlFileLogger({directory: root, role: "reverse-hub", processId: 11}).log("process.started", {runtimeMode: "reverse-hub"})
+
+    expect((await readdir(root)).sort()).toEqual([
+      "reverse-gateway-10.jsonl",
+      "reverse-hub-10.jsonl",
+      "reverse-hub-11.jsonl"
+    ])
+  }))
+
+  it("file logger caps only definitely exited same-role process families across PID reuse", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-obsolete-"))
+    after(() => cleanup(root))
+    const currentPid = process.pid
+    const firstExitedPid = currentPid + 10_001
+    const secondExitedPid = currentPid + 10_002
+    const thirdExitedPid = currentPid + 10_003
+    const exitedPids = new Set([firstExitedPid, secondExitedPid, thirdExitedPid])
+    const reusedPid = currentPid + 10_004
+    const livePid = currentPid + 10_005
+    const unknownPid = currentPid + 10_006
+    const timestamp = new Date("2026-01-01T00:00:00.000Z")
+    /** @type {string[]} */
+    const exitedFiles = []
+
+    for (const [offset, processId] of [...exitedPids].entries()) {
+      for (const rotation of ["", ".1"]) {
+        const file = `relay-${processId}.jsonl${rotation}`
+        await writeFile(join(root, file), "{}\n")
+        await utimes(join(root, file), timestamp, new Date(timestamp.getTime() + (2 + offset * 2 + (rotation === "" ? 1 : 0)) * 1000))
+        exitedFiles.push(file)
+      }
+    }
+    const reusedFiles = [`relay-${reusedPid}.jsonl`, `relay-${reusedPid}.jsonl.1`]
+    for (const [offset, file] of reusedFiles.entries()) {
+      await writeFile(join(root, file), "{}\n")
+      await utimes(join(root, file), timestamp, new Date(timestamp.getTime() + offset * 1000))
+    }
+    const liveFiles = [`relay-${livePid}.jsonl`, `relay-${livePid}.jsonl.1`]
+    const unknownFiles = [`relay-${unknownPid}.jsonl`, `relay-${unknownPid}.jsonl.1`]
+    const otherRoleFile = `reverse-hub-${currentPid + 10_007}.jsonl`
+    for (const file of [...liveFiles, ...unknownFiles, otherRoleFile]) await writeFile(join(root, file), "{}\n")
+
+    let reusedProbes = 0
+    const mocks = createMockScope()
+    after(() => mocks.restoreAll())
+    mocks.spyOn(process, "kill").mockImplementation((/** @type {number} */ processId, /** @type {string | number | undefined} */ signal) => {
+      expect(signal).toBe(0)
+      if (exitedPids.has(processId)) throw Object.assign(new Error("alphabeticsecret"), {code: "ESRCH"})
+      if (processId === reusedPid) {
+        reusedProbes += 1
+        if (reusedProbes === 1) throw Object.assign(new Error("exited before reuse"), {code: "ESRCH"})
+        return true
+      }
+      if (processId === livePid) return true
+      if (processId === unknownPid) throw Object.assign(new Error("lowentropysecret"), {code: "EPERM"})
+      throw new Error(`unexpected process probe: ${processId}`)
+    })
+
+    /** @type {string[]} */
+    const reports = []
+    const logger = createJsonlFileLogger({
+      directory: root,
+      role: "relay",
+      processId: currentPid,
+      maxFiles: 3,
+      stderr: {write: (/** @type {string} */ message) => { reports.push(message); return true }}
+    })
+    await expect(() => logger.log("process.started", {runtimeMode: "relay"})).not.toThrow()
+
+    const files = (await readdir(root)).sort()
+    expect(files.filter((file) => exitedFiles.includes(file))).toEqual([
+      `relay-${secondExitedPid}.jsonl`,
+      `relay-${thirdExitedPid}.jsonl`,
+      `relay-${thirdExitedPid}.jsonl.1`
+    ].sort())
+    expect(reusedFiles.filter((file) => files.includes(file))).toEqual(reusedFiles)
+    expect(liveFiles.filter((file) => files.includes(file))).toEqual(liveFiles)
+    expect(unknownFiles.filter((file) => files.includes(file))).toEqual(unknownFiles)
+    expect(files.includes(otherRoleFile)).toBeTruthy()
+    expect(files.includes(`relay-${currentPid}.jsonl`)).toBeTruthy()
+    expect(reusedProbes >= 2).toBeTruthy()
+    expect(reports).toEqual([])
+  }))
+
+  it("file and custom writer failures are isolated and reported once without error text", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-failure-"))
+    after(() => cleanup(root))
+    const blocker = join(root, "not-a-directory")
+    await writeFile(blocker, "occupied")
+    /** @type {string[]} */
+    const reports = []
+    const stderr = {write: (/** @type {string} */ message) => { reports.push(String(message)); return true }}
+    const fileLogger = createJsonlFileLogger({directory: join(blocker, "logs"), role: "relay", stderr})
+
+    await expect(() => fileLogger.log("process.started", {runtimeMode: "relay"})).not.toThrow()
+    await expect(() => fileLogger.log("runtime.status", {physicalConnections: 1})).not.toThrow()
+    expect(reports.length).toBe(1)
+    const report = reports[0]
+    if (report === undefined) throw new Error("Expected a captured log record")
+    expect(report).toMatch(/^Socketduct logger failure \(LOGGER_IO_ERROR\)\n$/)
+    expect(report).not.toMatch(/not-a-directory|ENOTDIR|occupied/)
+
+    /** @type {string[]} */
+    const customReports = []
+    const custom = createStructuredLogger({
+      role: "embedded-client",
+      stderr: {write: (/** @type {string} */ message) => { customReports.push(String(message)); return true }},
+      writeLine: () => { throw new Error("alphabeticsecret eyJhbGciOiJIUzI1NiJ9.private.signature") }
+    })
+    await expect(() => custom.log("transport.connected", {generation: 1})).not.toThrow()
+    await expect(() => custom.log("transport.disconnected", {generation: 1})).not.toThrow()
+    expect(customReports).toEqual(["Socketduct logger failure (LOGGER_WRITER_ERROR)\n"])
+
+    /** @type {string[]} */
+    const asyncReports = []
+    const asyncCustom = createStructuredLogger({
+      role: "embedded-client",
+      stderr: {write: (/** @type {string} */ message) => { asyncReports.push(String(message)); return true }},
+      writeLine: async () => { throw new Error("lowentropysecret") }
+    })
+    asyncCustom.log("transport.connected", {generation: 1})
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(asyncReports).toEqual(["Socketduct logger failure (LOGGER_WRITER_ERROR)\n"])
+  }))
+
+  it("file logger validates bounded rotation and safe role configuration", async () => withTestCleanup(async (after) => {
+    const root = await mkdtemp(join(tmpdir(), "socketduct-jsonl-validation-"))
+    after(() => cleanup(root))
+    await mkdir(join(root, "logs"))
+
+    await expect(() => createJsonlFileLogger({directory: join(root, "logs"), role: "../escape"})).toThrow(/role/)
+    await expect(() => createJsonlFileLogger({directory: join(root, "logs"), role: "relay", maxFileBytes: 100})).toThrow(/maxFileBytes/)
+    await expect(() => createJsonlFileLogger({directory: join(root, "logs"), role: "relay", maxFiles: 0})).toThrow(/maxFiles/)
+    await expect(() => createJsonlFileLogger({directory: join(root, "logs"), role: "relay", maxFiles: 101})).toThrow(/maxFiles/)
+  }))
+})