@remnic/coding-graph 9.3.759

package/src/lsp/degradation.ts

@@ -0,0 +1,86 @@
+/**
+ * LSP degradation codes — shaped like {@link SearchDegradation} from
+ * @remnic/core/search/port (issue #1536, CLAUDE.md rule 34).
+ *
+ * Every failure mode produces a DISTINCT code so callers (index_status,
+ * remnic doctor) can render per-language LSP state without conflating
+ * "server not installed" with "server timed out" or "protocol violation".
+ *
+ * The codes are the load-bearing signal — `detail` is optional and never
+ * carries `error.message` (which may contain absolute paths — rule 11).
+ */
+
+/**
+ * Backend identifier — always `"lsp"` so callers can distinguish LSP
+ * degradations from QMD/search degradations in a unified handler.
+ */
+export type LspBackend = "lsp";
+
+/**
+ * Distinct failure codes (rule 34 — never `[]`-on-error).
+ *
+ *   - `server_missing`      — the configured server binary is not on PATH
+ *                              or is not executable (probe phase).
+ *   - `handshake_timeout`   — `initialize` did not complete within
+ *                              `lsp.timeoutMs`.
+ *   - `handshake_error`     — server responded to `initialize` with an
+ *                              error or a malformed response.
+ *   - `request_timeout`     — a `textDocument/definition` request did
+ *                              not receive a response within the
+ *                              per-request deadline.
+ *   - `request_error`       — server returned a JSON-RPC error response
+ *                              for a resolution request.
+ *   - `protocol_error`      — malformed JSON-RPC frame (bad header,
+ *                              unparseable JSON, unknown method).
+ *   - `server_crashed`      — the child process exited unexpectedly
+ *                              mid-run.
+ *   - `budget_exhausted`    — `lsp.maxRequestsPerRun` reached; remaining
+ *                              call sites keep their Phase A resolution.
+ *   - `not_enabled`         — `lsp.enabled` is `false`; no probe attempted.
+ *   - `unknown_language`    — the file's language has no registered
+ *                              server spec and none was overridden in
+ *                              `lsp.servers`.
+ */
+export type LspDegradationCode =
+  | "server_missing"
+  | "handshake_timeout"
+  | "handshake_error"
+  | "request_timeout"
+  | "request_error"
+  | "protocol_error"
+  | "server_crashed"
+  | "budget_exhausted"
+  | "not_enabled"
+  | "unknown_language";
+
+/**
+ * Tagged degradation — mirrors the shape of {@link SearchDegradation}.
+ * `ok: false` results from the client/registry/resolution surface carry
+ * this object so consumers can switch on `code` programmatically.
+ */
+export interface LspDegradation {
+  readonly backend: LspBackend;
+  readonly code: LspDegradationCode;
+  readonly detail?: string;
+}
+
+/**
+ * Tagged-result helpers — the shared discriminated-union pattern used
+ * throughout the coding-graph package (rule 34). Every LSP surface
+ * returns `{ ok: true; … }` on success or `{ ok: false; degradation }`
+ * on failure — never throws, never returns `[]` to mean "error".
+ */
+export type LspResult<T> =
+  | ({ readonly ok: true } & T)
+  | { readonly ok: false; readonly degradation: LspDegradation };
+
+/**
+ * Construct a degradation object. Kept as a factory rather than a class
+ * so callers can spread it into a result without `new`.
+ */
+export function lspDegradation(
+  code: LspDegradationCode,
+  detail?: string,
+): LspDegradation {
+  return detail !== undefined ? { backend: "lsp", code, detail } : { backend: "lsp", code };
+}

package/src/lsp/fixtures/fake-server.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * Fake LSP server — a scripted JSON-RPC-over-stdio responder for tests.
+ *
+ * Checked into the package's test fixtures. Synthetic responses only —
+ * it does NOT analyze code. Instead it reads a scenario from argv and
+ * produces canned LSP-shaped responses that match the real protocol
+ * wire format (rule 33 — cite spec version: LSP 3.17).
+ *
+ * Scenario is passed as the LAST argv element (after `--`):
+ *
+ *   node fake-server.mjs -- <scenario-name>
+ *
+ * Scenarios:
+ *   happy             — full handshake + returns definition locations.
+ *   missing           — exits immediately with code 1.
+ *   handshake_timeout — accepts initialize request but never responds.
+ *   request_timeout   — completes handshake but never responds to definition.
+ *   protocol_error    — sends a malformed frame after receiving initialize.
+ *   crash_after_start — completes handshake, then exits mid-run.
+ */
+
+import process from "node:process";
+
+const scenario = process.argv[process.argv.length - 1];
+
+// ──────────────────────────────────────────────────────────────────────────
+// Persistent stdin buffer — survives across readFrame calls so data from
+// a combined chunk that contains multiple frames is not lost.
+// ──────────────────────────────────────────────────────────────────────────
+
+let stdinBuf = "";
+let stdinWaiters = [];
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  stdinBuf += chunk;
+  // Notify all waiters that new data arrived.
+  const waiters = stdinWaiters;
+  stdinWaiters = [];
+  for (const w of waiters) w();
+});
+process.stdin.on("end", () => {
+  const waiters = stdinWaiters;
+  stdinWaiters = [];
+  for (const w of waiters) w();
+});
+
+/** Wait for more stdin data to arrive. */
+function waitForData() {
+  const { promise, resolve } = Promise.withResolvers();
+  stdinWaiters.push(resolve);
+  return promise;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Frame I/O helpers — read/write Content-Length-prefixed messages.
+// ──────────────────────────────────────────────────────────────────────────
+
+function writeFrame(obj) {
+  const body = JSON.stringify(obj);
+  const byteLength = Buffer.byteLength(body, "utf8");
+  process.stdout.write(`Content-Length: ${byteLength}\r\n\r\n${body}`);
+}
+
+async function readFrame() {
+  // Loop until we have a complete frame in the persistent buffer.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const sep = stdinBuf.indexOf("\r\n\r\n");
+    if (sep < 0) {
+      // No complete header yet — wait for more data.
+      if (stdinBuf === null) return null; // stdin ended
+      await waitForData();
+      continue;
+    }
+    const header = stdinBuf.slice(0, sep);
+    const match = /Content-Length:\s*(\d+)/i.exec(header);
+    if (!match) {
+      // Malformed — treat as end of stream.
+      return null;
+    }
+    const contentLength = Number(match[1]);
+    const bodyStart = sep + 4;
+    const bodyEnd = bodyStart + contentLength;
+    if (stdinBuf.length < bodyEnd) {
+      // Body not fully received — wait for more.
+      await waitForData();
+      continue;
+    }
+    const body = stdinBuf.slice(bodyStart, bodyEnd);
+    // Consume the frame from the persistent buffer, keeping any residual.
+    stdinBuf = stdinBuf.slice(bodyEnd);
+    try {
+      return JSON.parse(body);
+    } catch {
+      return null;
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Scenario handlers
+// ──────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  switch (scenario) {
+    case "missing":
+      process.exit(1);
+
+    case "handshake_timeout":
+      await readFrame(); // consume initialize, never respond
+      await new Promise(() => {}); // hang forever
+      return;
+
+    case "request_timeout": {
+      const init = await readFrame();
+      writeFrame({
+        jsonrpc: "2.0",
+        id: init.id,
+        result: {
+          capabilities: { definitionProvider: true },
+          serverInfo: { name: "fake-timeout" },
+        },
+      });
+      await readFrame(); // initialized
+      await readFrame(); // definition request — never respond
+      await new Promise(() => {});
+      return;
+    }
+
+    case "protocol_error": {
+      await readFrame(); // initialize
+      process.stdout.write("THIS IS NOT A VALID LSP FRAME\r\n\r\n");
+      process.exit(0);
+      return;
+    }
+
+    case "crash_after_start": {
+      const init = await readFrame();
+      writeFrame({
+        jsonrpc: "2.0",
+        id: init.id,
+        result: {
+          capabilities: { definitionProvider: true },
+          serverInfo: { name: "fake-crash" },
+        },
+      });
+      await readFrame(); // initialized
+      process.exit(1); // crash mid-run
+      return;
+    }
+
+    case "happy":
+    default: {
+      const init = await readFrame();
+      if (!init) return;
+      writeFrame({
+        jsonrpc: "2.0",
+        id: init.id,
+        result: {
+          capabilities: { definitionProvider: true },
+          serverInfo: { name: "fake-happy", version: "1.0.0" },
+        },
+      });
+      await readFrame(); // initialized
+      await readFrame(); // didOpen
+
+      // Answer definition/shutdown/exit until stdin closes.
+      // eslint-disable-next-line no-constant-condition
+      while (true) {
+        const req = await readFrame();
+        if (!req) return;
+        if (req.method === "textDocument/definition") {
+          const envLoc = process.env.FAKE_LSP_DEFINITION;
+          const result = envLoc
+            ? JSON.parse(envLoc)
+            : [
+                {
+                  uri: "file:///fake/src/target.ts",
+                  range: {
+                    start: { line: 0, character: 0 },
+                    end: { line: 0, character: 10 },
+                  },
+                },
+              ];
+          writeFrame({ jsonrpc: "2.0", id: req.id, result });
+        } else if (req.method === "shutdown") {
+          writeFrame({ jsonrpc: "2.0", id: req.id, result: null });
+        } else if (req.method === "exit") {
+          process.exit(0);
+        }
+      }
+    }
+  }
+}
+
+main().catch(() => process.exit(1));

package/src/lsp/framing.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Framing edge-case tests (issue #1555 step 2 — prove-fail-before).
+ *
+ * Covers the off-by-one and split-buffer traps that make LSP framing
+ * the most error-prone part of the client:
+ *   - single complete frame
+ *   - frame split across multiple chunks (body boundary)
+ *   - header split across chunks (separator boundary)
+ *   - multiple frames in one chunk
+ *   - partial frame (body not yet complete) → zero messages
+ *   - Content-Length counts UTF-8 BYTES not UTF-16 code units
+ *   - malformed header (no Content-Length) → decode error
+ *   - invalid JSON body → decode error
+ *   - empty feed → zero messages, no throw
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  LspFrameDecoder,
+  encodeLspFrame,
+} from "./framing.js";
+
+test("encodeLspFrame: Content-Length header counts UTF-8 bytes, not UTF-16 code units", () => {
+  // The emoji 𝕏 is 4 UTF-8 bytes (F0 9D 95 8F) but 2 UTF-16 code units.
+  const frame = encodeLspFrame({ method: "test", params: { text: "𝕏" } });
+  // The body is the JSON-serialized object. We check that the header
+  // Content-Length matches Buffer.byteLength of the body.
+  const headerEnd = frame.indexOf("\r\n\r\n");
+  const header = frame.slice(0, headerEnd);
+  const body = frame.slice(headerEnd + 4);
+  const match = /Content-Length:\s*(\d+)/i.exec(header);
+  assert.ok(match, "header must contain Content-Length");
+  const declared = Number(match[1]);
+  const actual = Buffer.byteLength(body, "utf8");
+  assert.equal(declared, actual, "Content-Length must match UTF-8 byte count");
+});
+
+test("decode: single complete frame in one chunk", () => {
+  const dec = new LspFrameDecoder();
+  const frame = encodeLspFrame({ jsonrpc: "2.0", id: 1, result: { ok: true } });
+  const result = dec.feed(frame);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], { jsonrpc: "2.0", id: 1, result: { ok: true } });
+  }
+  assert.equal(dec.hasResidual, false);
+});
+
+test("decode: frame body split across two chunks", () => {
+  const dec = new LspFrameDecoder();
+  const frame = encodeLspFrame({ jsonrpc: "2.0", id: 1, result: { ok: true } });
+  const headerEnd = frame.indexOf("\r\n\r\n") + 4;
+  const header = frame.slice(0, headerEnd);
+  const body = frame.slice(headerEnd);
+  const mid = Math.floor(body.length / 2);
+
+  // First chunk: header + half the body → zero messages.
+  let result = dec.feed(header + body.slice(0, mid));
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.messages.length, 0);
+
+  // Second chunk: rest of body → one message.
+  result = dec.feed(body.slice(mid));
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], { jsonrpc: "2.0", id: 1, result: { ok: true } });
+  }
+});
+
+test("decode: header separator split across two chunks", () => {
+  const dec = new LspFrameDecoder();
+  const frame = encodeLspFrame({ jsonrpc: "2.0", id: 1, result: "x" });
+  // Split right in the middle of \r\n\r\n.
+  const sepIdx = frame.indexOf("\r\n\r\n");
+  const splitPoint = sepIdx + 2; // after first \r\n, before second \r\n
+
+  let result = dec.feed(frame.slice(0, splitPoint));
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.messages.length, 0);
+
+  result = dec.feed(frame.slice(splitPoint));
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], { jsonrpc: "2.0", id: 1, result: "x" });
+  }
+});
+
+test("decode: multiple frames in one chunk", () => {
+  const dec = new LspFrameDecoder();
+  const f1 = encodeLspFrame({ jsonrpc: "2.0", id: 1, result: "a" });
+  const f2 = encodeLspFrame({ jsonrpc: "2.0", id: 2, result: "b" });
+  const f3 = encodeLspFrame({ jsonrpc: "2.0", id: 3, result: "c" });
+
+  const result = dec.feed(f1 + f2 + f3);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 3);
+    assert.deepEqual(result.messages[0], { jsonrpc: "2.0", id: 1, result: "a" });
+    assert.deepEqual(result.messages[1], { jsonrpc: "2.0", id: 2, result: "b" });
+    assert.deepEqual(result.messages[2], { jsonrpc: "2.0", id: 3, result: "c" });
+  }
+  assert.equal(dec.hasResidual, false);
+});
+
+test("decode: partial header (no separator yet) → zero messages, no throw", () => {
+  const dec = new LspFrameDecoder();
+  const result = dec.feed("Content-Length: 10\r\n");
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.messages.length, 0);
+  assert.equal(dec.hasResidual, true);
+});
+
+test("decode: malformed header (no Content-Length) → decode error", () => {
+  const dec = new LspFrameDecoder();
+  const result = dec.feed("Content-Type: text/plain\r\n\r\n{}");
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.error.kind, "malformed_header");
+  }
+});
+
+test("decode: invalid JSON body → decode error", () => {
+  const dec = new LspFrameDecoder();
+  const body = "{ not valid json";
+  const byteLength = Buffer.byteLength(body, "utf8");
+  const frame = `Content-Length: ${byteLength}\r\n\r\n${body}`;
+  const result = dec.feed(frame);
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.error.kind, "json_parse_error");
+  }
+});
+
+test("decode: empty feed → zero messages, no throw", () => {
+  const dec = new LspFrameDecoder();
+  const result = dec.feed("");
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.messages.length, 0);
+  assert.equal(dec.hasResidual, false);
+});
+
+test("decode: UTF-8 multi-byte body — Content-Length matches byte count", () => {
+  const dec = new LspFrameDecoder();
+  const obj = { jsonrpc: "2.0", id: 1, result: "𝕏𝕏𝕏" };
+  const frame = encodeLspFrame(obj);
+  const result = dec.feed(frame);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], obj);
+  }
+});
+
+test("decode: sequential frames after partial — scan offset resets correctly", () => {
+  // Regression guard: after extracting a frame that was split, the
+  // scanOffset must reset so the next frame's separator is found from
+  // the beginning of the new buffer, not from a stale offset.
+  const dec = new LspFrameDecoder();
+  const f1 = encodeLspFrame({ id: 1 });
+  const f2 = encodeLspFrame({ id: 2 });
+
+  // Feed f1 in two chunks to force a split-extract cycle.
+  const mid = Math.floor(f1.length / 2);
+  dec.feed(f1.slice(0, mid));
+  let result = dec.feed(f1.slice(mid));
+  assert.equal(result.ok, true);
+  if (result.ok) assert.equal(result.messages.length, 1);
+
+  // Now feed f2 — it should parse cleanly from the reset offset.
+  result = dec.feed(f2);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.messages.length, 1);
+    assert.deepEqual(result.messages[0], { id: 2 });
+  }
+});

package/src/lsp/framing.ts

@@ -0,0 +1,177 @@
+/**
+ * Length-prefixed LSP framing — `Content-Length: <N>\r\n\r\n` headers
+ * followed by exactly `<N>` bytes of JSON body (LSP 3.17 §6.1 — Base Protocol).
+ *
+ * This is the one module where off-by-one and split-buffer bugs hide.
+ * The parser tracks a RUNNING OFFSET — it never re-scans bytes a
+ * previous scan already confirmed separator-free (rule 32).
+ */
+
+// ──────────────────────────────────────────────────────────────────────────
+// Encoder — serialize a JSON-RPC message into a Content-Length frame.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Encode a JSON-RPC message as a Content-Length-prefixed frame ready to
+ * write to the server's stdin. Uses UTF-8 — the LSP base protocol
+ * mandates UTF-8 content encoding (§6.1).
+ */
+export function encodeLspFrame(message: unknown): string {
+  const body = JSON.stringify(message);
+  // Content-Length counts UTF-8 BYTES, not JS UTF-16 code units. Node's
+  // Buffer.byteLength accounts for multi-byte sequences.
+  const byteLength = Buffer.byteLength(body, "utf8");
+  return `Content-Length: ${byteLength}\r\n\r\n${body}`;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Decoder — streaming parser that accumulates chunks and yields complete
+// messages. Never throws on partial input — it just returns fewer messages
+// and retains the residual for the next feed() call.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Reason for a decode failure. A `protocol_error` degradation surfaces
+ * the specific reason so the caller can distinguish "bad header" from
+ * "unparseable JSON body".
+ */
+export type FrameDecodeErrorKind =
+  | "malformed_header" // header line is not `Content-Length: <digits>`
+  | "json_parse_error"; // body is not valid JSON
+
+export interface FrameDecodeError {
+  readonly kind: FrameDecodeErrorKind;
+  readonly detail: string;
+}
+
+export interface FrameDecodeSuccess {
+  readonly ok: true;
+  readonly messages: unknown[];
+}
+
+export type FrameDecodeResult = FrameDecodeSuccess | { readonly ok: false; readonly error: FrameDecodeError };
+
+// Sentinel for the header/body separator — `\r\n\r\n` (as bytes).
+const HEADER_SEPARATOR = Buffer.from("\r\n\r\n");
+const HEADER_SEPARATOR_LEN = HEADER_SEPARATOR.length;
+
+/**
+ * Streaming LSP frame decoder. Feed raw Buffer or string chunks via
+ * {@link feed}; each call returns the complete JSON messages parsed
+ * since the last call, plus any error if a frame was malformed.
+ *
+ * Works with BYTES internally because Content-Length counts UTF-8 bytes
+ * (LSP 3.17 §6.1), not UTF-16 code units. A string-based buffer would
+ * mis-slice any body containing multi-byte characters (𝕏, emoji, CJK).
+ *
+ * The decoder maintains a running byte-buffer and a scan offset. After
+ * each feed, consumed bytes are sliced away so the buffer never grows
+ * unbounded across a long session (rule 11 — no unbounded state).
+ */
+export class LspFrameDecoder {
+  private buffer = Buffer.alloc(0);
+  /**
+   * Scan offset into {@link buffer}. The header scan resumes here on
+   * the next feed() — never re-scans bytes already confirmed to not
+   * contain the separator (rule 32). Reset to 0 after each consumed
+   * frame because slicing the buffer discards those bytes.
+   */
+  private scanOffset = 0;
+
+  /**
+   * Feed a raw chunk (Buffer or string) from the server's stdout.
+   * Returns all complete messages parsed from the accumulated buffer
+   * since the last call, or the first decode error encountered (the
+   * decoder stops on error — a protocol violation means the stream is
+   * corrupt and further parsing is undefined).
+   */
+  feed(chunk: Buffer | string): FrameDecodeResult {
+    const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    this.buffer = this.buffer.length === 0 ? Buffer.from(buf) : Buffer.concat([this.buffer, buf]);
+    const messages: unknown[] = [];
+
+    // Loop: extract as many complete frames as the current buffer holds.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const sepIdx = this.buffer.indexOf(HEADER_SEPARATOR, this.scanOffset);
+      if (sepIdx < 0) {
+        // No complete header yet. Advance scanOffset past the bytes
+        // already confirmed separator-free (rule 32). The separator is
+        // 4 bytes, so a partial match could start up to 3 bytes before
+        // the current end.
+        this.scanOffset = Math.max(0, this.buffer.length - (HEADER_SEPARATOR_LEN - 1));
+        return { ok: true, messages };
+      }
+
+      const headerBlock = this.buffer.subarray(0, sepIdx).toString("utf8");
+      const contentLength = parseContentLength(headerBlock);
+      if (contentLength === null) {
+        return {
+          ok: false,
+          error: {
+            kind: "malformed_header",
+            detail: `header block has no valid Content-Length: ${JSON.stringify(headerBlock)}`,
+          },
+        };
+      }
+
+      const bodyStart = sepIdx + HEADER_SEPARATOR_LEN;
+      const bodyEnd = bodyStart + contentLength;
+      if (this.buffer.length < bodyEnd) {
+        // Body not fully received yet. Back up scanOffset to just before
+        // the separator so the next feed re-finds it.
+        this.scanOffset = Math.max(0, sepIdx - (HEADER_SEPARATOR_LEN - 1));
+        return { ok: true, messages };
+      }
+
+      const bodyBytes = this.buffer.subarray(bodyStart, bodyEnd);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(bodyBytes.toString("utf8"));
+      } catch (e) {
+        return {
+          ok: false,
+          error: {
+            kind: "json_parse_error",
+            detail: `body is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+          },
+        };
+      }
+      messages.push(parsed);
+
+      // Slice consumed bytes off the front — subarray returns a view
+      // into the same memory; concat on the next feed replaces it.
+      this.buffer = this.buffer.subarray(bodyEnd);
+      this.scanOffset = 0;
+    }
+  }
+
+  /** True if there is un-consumed residual data in the buffer. */
+  get hasResidual(): boolean {
+    return this.buffer.length > 0;
+  }
+
+  /** Reset the decoder to a clean state (test seam). */
+  reset(): void {
+    this.buffer = Buffer.alloc(0);
+    this.scanOffset = 0;
+  }
+}
+
+/**
+ * Parse the `Content-Length` value from a header block. Returns the byte
+ * count or null if the header is absent or malformed. LSP headers are
+ * case-insensitive and may appear in any order, but Content-Length is
+ * mandatory (§6.1).
+ */
+function parseContentLength(headerBlock: string): number | null {
+  const lines = headerBlock.split("\r\n");
+  for (const line of lines) {
+    const match = /^Content-Length:\s*(\d+)\s*$/i.exec(line);
+    if (match) {
+      const n = Number(match[1]);
+      return Number.isFinite(n) && n >= 0 ? n : null;
+    }
+  }
+  return null;
+}