getculpa 0.0.1 → 1.0.2

package/assets/register.mjs

@@ -0,0 +1,713 @@
+// Culpa Node runtime collector — the thin shipper (CF13-T5, D-082 ruling B).
+// tasks/collector-plan.md §TASK-5: ZERO usage extraction happens in this
+// file. Its entire job is to observe raw request/response evidence for
+// outbound HTTP traffic and hand it to culpa-collectord (a separate Rust
+// process, native/culpa-collector) over loopback, which runs the EXISTING
+// culpa-capture normalizers. Duplicating usage extraction in JavaScript
+// would create a second cost-truth engine — explicitly forbidden by D-082.
+// No npm dependencies: this file must run as a bare preload in any Node app.
+//
+// Loaded via NODE_OPTIONS="--import=<file URL to this file>" (deployment
+// configuration only — never a source edit; see
+// native/culpa-collector/tests/collector_gate.rs's module doc). Runs BEFORE
+// any application code.
+//
+// FAIL-OPEN — the single most important property here (tasks/collector-plan.
+// md §TASK-5): every internal error is swallowed. If the collector is down,
+// unreachable, slow, or this file itself throws, the application's own
+// traffic must be completely unaffected. A spend tool that takes down
+// production is worse than no spend tool.
+//
+// TWO HOOKS, BOTH REQUIRED (tasks/open-loops.md "T5 mechanism VERIFIED by
+// execution", measured on Node v20.19.6): Node's global `fetch` (and the
+// OpenAI SDK, which rides it) goes through undici's GLOBAL DISPATCHER; the
+// Anthropic SDK (0.27.3) goes through `http.request` directly and is
+// INVISIBLE to a dispatcher-only hook. Hooking only one leaves an entire
+// real SDK uninstrumented while a fetch-only fixture stays green — exactly
+// the stub-only false-green D-082 item 3 warned about.
+//
+// NEVER ALTERS APP BEHAVIOR: every hook here is a TEE, never a
+// replacement — the wrapped dispatch/response handlers/streams always
+// forward to the original in full, with the original's return values passed
+// back unchanged. Nothing here ever consumes a stream the app would
+// otherwise read, delays a response, or changes what the app sees (verified
+// end to end this session — tasks/open-loops.md: "the app's own
+// `ar.content[0].text` and `ar.usage` came back intact").
+//
+// AI-TRAFFIC DISCRIMINATION (CF21-T1, D-091): this collector sits beside a
+// customer's WHOLE outbound traffic — Stripe, Firebase, Sentry, anything
+// else — not just their LLM calls. See the "AI-traffic discrimination"
+// section below (`isAiShapedObservation` and friends): finish() ships an
+// observation ONLY when its URL is a known AI-provider shape or its
+// captured body is affirmatively AI-shaped. This is the earliest-boundary
+// half of the discrimination (defense in depth) — the collectord-side
+// filter (native/culpa-collector/src/discriminate.rs) is the authoritative
+// one; the mailbox boundary is the hard rule D-091 states.
+
+import http from "node:http";
+import https from "node:https";
+
+// ─────────────────────────────────────────────────────────── configuration
+
+const COLLECTOR_URL = process.env.CULPA_COLLECTOR_URL;
+const MAX_BODY_BYTES = 262_144; // 256 KiB per side — bounded buffer, never unbounded growth
+const MAX_IN_FLIGHT = 256; // bounded concurrent observation buffers
+const SHIP_TIMEOUT_MS = 2_000;
+// OBSERVATION_MAX_LIFETIME_MS — hard ceiling on how long one observation may
+// hold its inFlight slot. If an application receives a response and never
+// reads it (no `data` listener, no resume(), no pipe() — the exact shape CR-1
+// requires this file to leave alone), Node's Agent fires NO terminal event on
+// either req or res — not 'end', not 'close' — until the body is drained:
+// measured directly, this holds for well past 6 seconds, and for a real
+// (non-Node) upstream with no idle timeout it can hold forever. Without a
+// ceiling, MAX_IN_FLIGHT such requests permanently exhaust inFlight and
+// newObservation() returns null for the rest of the process's lifetime — the
+// same failure mode CR-2 fixed for "aborted mid-flight", but for "never
+// touched at all". 120s is generous enough that a real, slow LLM completion
+// (streamed or not) is never mistaken for a leak, while still recovering a
+// leaked slot within a bounded, human-noticeable time instead of never.
+// The env override exists ONLY for this file's own test suite (see
+// native/culpa-collector/tests/observation_lifetime_timeout.rs), which
+// cannot wait 120s per assertion; production deployments should never set it.
+const OBSERVATION_MAX_LIFETIME_MS = (() => {
+  const override = Number(process.env.CULPA_OBSERVATION_MAX_LIFETIME_MS);
+  return Number.isFinite(override) && override > 0 ? override : 120_000;
+})();
+
+// The ORIGINAL, unpatched http.request — used ONLY for this file's own
+// outbound POST to culpa-collectord, so the shipper never observes (and
+// never self-loops on) its own traffic. Captured before any patching below.
+const originalHttpRequest = http.request.bind(http);
+
+let inFlight = 0;
+
+// ────────────────────────────────────── AI-traffic discrimination (CF21-T1)
+
+// D-091 ruling (.gsd/decisions.ndjson): "unrelated outbound traffic
+// (Stripe/Firebase/Sentry/anything non-AI) must never be collected,
+// persisted, or shipped to the mailbox — only normalized AI usage evidence
+// leaves the capture plane." EARLIEST-BOUNDARY DISCARD: this file decides
+// whether to ship() at all, BEFORE crossing even the loopback socket to
+// culpa-collectord — shrinking what a revenue service's Stripe/Firebase/
+// Sentry/etc. traffic ever sends over IPC. This is DEFENSE IN DEPTH, not
+// the hard rule: native/culpa-collector/src/discriminate.rs on the collectord
+// side is the AUTHORITATIVE filter (the mailbox boundary is where the rule
+// is actually enforced) — a gap in the logic below is not itself a privacy
+// violation, since nothing reaches the mailbox regardless. Kept as a close
+// mirror of discriminate.rs's signals anyway (rather than "ship everything,
+// let the Rust side sort it out") specifically to reduce loopback traffic on
+// a busy revenue service, per this task's design constraint.
+//
+// PROTOCOL-SHAPE, NOT A HOST ALLOWLIST: `urlLooksLikeKnownAiEndpoint` below
+// is a FAST-PATH ACCEPT HINT ONLY (mirrors endpoint.rs's `match_endpoint`) —
+// it can never be the sole reason something is REJECTED. Any URL it doesn't
+// recognize still gets the real body-shape check
+// (`isAiShapedObservation`), never an automatic discard.
+
+/**
+ * Mirrors native/culpa-collector/src/endpoint.rs's `match_endpoint` (path
+ * checked first — host-agnostic, exactly why the stub fixtures on a bare
+ * 127.0.0.1 loopback host still match — then a hostname fallback for the
+ * real providers' production API hosts). Deliberately duplicated rather
+ * than imported: this file ships as a bare `--import` preload with ZERO npm
+ * dependencies and no build step, so it cannot depend on the Rust crate.
+ * If endpoint.rs's list ever changes, update this to match (both sides stay
+ * independently unit-testable, so a drift shows up as a real test failure,
+ * never a silent gap).
+ */
+function urlLooksLikeKnownAiEndpoint(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false; // unparseable URL — no fast-path hint either way
+  }
+  const path = parsed.pathname;
+  if (
+    path.includes("/v1/chat/completions") ||
+    path.includes("/v1/completions") ||
+    path.includes("/v1/responses") ||
+    path.includes("/v1/messages")
+  ) {
+    return true;
+  }
+  if (path.includes("/models/") && (path.includes(":generateContent") || path.includes(":streamGenerateContent"))) {
+    return true;
+  }
+  const host = parsed.hostname.toLowerCase();
+  return (
+    host.endsWith("api.openai.com") ||
+    host.endsWith("api.anthropic.com") ||
+    host.endsWith("generativelanguage.googleapis.com")
+  );
+}
+
+/**
+ * REQUEST shape signal (discriminate.rs's `request_is_ai_shaped`, mirrored):
+ * a JSON object carrying a non-empty string "model" AND one of "messages"
+ * (array), "prompt" (string/array), or "input" (string/array — CF21-T1
+ * review finding 2: an object-shaped "input", e.g. a quoting-service form
+ * payload with an unrelated "model" field, is NOT sufficient; only a
+ * string/array matches the OpenAI Responses API's real shape, the same
+ * precedent "prompt" already follows) — the OpenAI-compatible
+ * chat/completions/responses convention (also Anthropic's Messages API
+ * request shape).
+ */
+function requestIsAiShaped(bodyText) {
+  if (!bodyText) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return false;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+  if (typeof parsed.model !== "string" || parsed.model.length === 0) return false;
+  if (Array.isArray(parsed.messages)) return true;
+  if (typeof parsed.prompt === "string" || Array.isArray(parsed.prompt)) return true;
+  if (typeof parsed.input === "string" || Array.isArray(parsed.input)) return true;
+  return false;
+}
+
+/** True when `value` (or any element of an array `value`) carries a
+ * top-level "usage" key whose value is a JSON object — RESPONSE shape signal
+ * (discriminate.rs's `value_has_usage_like_block`, mirrored). */
+function valueHasUsageLikeBlock(value) {
+  if (Array.isArray(value)) return value.some(valueHasUsageLikeBlock);
+  if (value !== null && typeof value === "object") {
+    const usage = value.usage;
+    return !!(usage && typeof usage === "object" && !Array.isArray(usage));
+  }
+  return false;
+}
+
+/**
+ * RESPONSE shape signal, handling both a plain JSON body and an SSE-framed
+ * streaming one ("data: <json>" lines — the same framing
+ * culpa-capture/src/record.rs's `served_model_from` parses).
+ */
+function responseHasUsageLikeBlock(bodyText) {
+  if (!bodyText) return false;
+  try {
+    return valueHasUsageLikeBlock(JSON.parse(bodyText));
+  } catch {
+    return bodyText
+      .split("\n")
+      .filter((line) => line.startsWith("data: "))
+      .map((line) => line.slice(6))
+      .filter((payload) => payload !== "[DONE]")
+      .some((payload) => {
+        try {
+          return valueHasUsageLikeBlock(JSON.parse(payload));
+        } catch {
+          return false;
+        }
+      });
+  }
+}
+
+/**
+ * The body-shape decision for a URL the fast-path hint above didn't
+ * recognize (discriminate.rs's `is_ai_shaped`, mirrored): true when EITHER
+ * signal fires. Pure, unit-testable in isolation — no I/O, only the strings
+ * this file already accumulated in its own bounded buffers.
+ */
+function isAiShapedObservation(requestBody, responseBody) {
+  return requestIsAiShaped(requestBody) || responseHasUsageLikeBlock(responseBody);
+}
+
+function toBuffer(chunk) {
+  if (chunk === undefined || chunk === null) return null;
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (typeof chunk === "string") return Buffer.from(chunk, "utf8");
+  return null; // not a plain string/Buffer (e.g. a stream) — never guess, never consume it
+}
+
+// ────────────────────────────────────────────────────────────── shipping
+
+/**
+ * Fire-and-forget POST to culpa-collectord. Never awaited by any caller,
+ * never throws, never delays or blocks the app — every failure mode
+ * (collector down, DNS failure, timeout, malformed URL) is swallowed here.
+ * This is F5.2's fail-open guarantee, structurally: nothing upstream of this
+ * function ever inspects its outcome.
+ */
+function ship(observation) {
+  if (!COLLECTOR_URL) return;
+  let target;
+  try {
+    target = new URL("/observe", COLLECTOR_URL);
+  } catch {
+    return; // malformed CULPA_COLLECTOR_URL — fail open, never throw
+  }
+  let body;
+  try {
+    body = Buffer.from(JSON.stringify(observation), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const req = originalHttpRequest(target, {
+      method: "POST",
+      headers: { "content-type": "application/json", "content-length": body.length },
+      timeout: SHIP_TIMEOUT_MS,
+    });
+    // No response body is ever read — culpa-collectord's answer is
+    // irrelevant to the shipper. 'error'/'timeout' are handled so an
+    // unhandled 'error' event can never crash the process (fail-open).
+    req.on("error", () => {});
+    req.on("timeout", () => req.destroy());
+    req.end(body);
+  } catch {
+    // fail open — a throw here must never propagate into app code
+  }
+}
+
+// ──────────────────────────────────────────────────── bounded observation
+
+/**
+ * One in-flight request/response being teed. Bounded: stops accumulating
+ * past MAX_BODY_BYTES PER SIDE and marks that side's own truncation flag
+ * (CF21-T1 review finding 1 — PER-SIDE, not one combined flag) rather than
+ * growing without limit — culpa-collectord then degrades honestly
+ * (envelope.rs's per-side truncation handling) rather than parsing a
+ * partial body.
+ */
+function newObservation(url) {
+  if (inFlight >= MAX_IN_FLIGHT) {
+    return null; // bounded: too many concurrent buffers — observe nothing rather than grow unbounded
+  }
+  inFlight++;
+  let requestChunks = [];
+  let requestBytes = 0;
+  let responseChunks = [];
+  let responseBytes = 0;
+  let requestTruncated = false;
+  let responseTruncated = false;
+  let status = 0;
+  const startedAtMs = Date.now();
+  let finished = false;
+
+  function append(chunk, chunksRef, bytesKey) {
+    if (!chunk) return chunksRef;
+    const nextBytes = (bytesKey === "request" ? requestBytes : responseBytes) + chunk.length;
+    if (bytesKey === "request") requestBytes = nextBytes;
+    else responseBytes = nextBytes;
+    if (nextBytes > MAX_BODY_BYTES) {
+      if (bytesKey === "request") requestTruncated = true;
+      else responseTruncated = true;
+      return [];
+    }
+    chunksRef.push(chunk);
+    return chunksRef;
+  }
+
+  function settle() {
+    if (finished) return false;
+    finished = true;
+    inFlight--;
+    clearTimeout(lifetimeTimer); // no accumulating timers past this observation's own life
+    return true;
+  }
+
+  function finish() {
+    if (!settle()) return;
+    // Blank only the side that actually overflowed — the intact side's
+    // bytes are used exactly as captured (still never persisted past this
+    // function: the strip-before-mailbox rule lives in envelope.rs, this is
+    // only the ephemeral wire payload to culpa-collectord).
+    const requestBody = requestTruncated ? "" : Buffer.concat(requestChunks).toString("utf8");
+    const responseBody = responseTruncated ? "" : Buffer.concat(responseChunks).toString("utf8");
+    // CF21-T1 (D-091) earliest-boundary discard. A known-AI URL always ships
+    // (the fast-path hint — matches the OLD behavior for every existing
+    // provider/transport-matrix row, unaffected by this change). Otherwise:
+    // FINDING 1 fix — only discard here when BOTH sides are gone (no intact
+    // side left to prove AI-shapedness either way) or when whatever IS
+    // intact still isn't AI-shaped. Before this fix, a single combined flag
+    // discarded an intact, AI-shaped request just because its response
+    // alone had overflowed — exactly the case `isAiShapedObservation` below
+    // must still get a chance to see, mirroring discriminate.rs's own
+    // per-side fix (envelope.rs's `build_envelope_for_unmatched_url`). An
+    // intact-but-not-AI-shaped body (Stripe/Firebase/Sentry/anything else)
+    // still never crosses the loopback socket at all. This is DEFENSE IN
+    // DEPTH only — native/culpa-collector/src/discriminate.rs is the
+    // authoritative filter regardless of what this file decides.
+    if (!urlLooksLikeKnownAiEndpoint(url)) {
+      if (requestTruncated && responseTruncated) {
+        return;
+      }
+      if (!isAiShapedObservation(requestBody, responseBody)) {
+        return;
+      }
+    }
+    ship({
+      url,
+      status,
+      occurredAtMs: startedAtMs,
+      latencyMs: Date.now() - startedAtMs,
+      requestBody,
+      responseBody,
+      requestTruncated,
+      responseTruncated,
+      // Derived OR, kept for any OTHER consumer of this wire shape still
+      // reading the old combined flag — culpa-collectord itself reads the
+      // two granular fields above (server.rs's parse_observation).
+      bodyTruncated: requestTruncated || responseTruncated,
+    });
+  }
+
+  function abort() {
+    // no ship() on a failed/aborted call — nothing complete to report; an
+    // app-level retry (if any) produces its own, separate observation
+    settle();
+  }
+
+  // Expiry policy: SHIP what was actually observed, forced through the
+  // SAME truncation-degrade path the oversized-body case already uses
+  // (both sides marked truncated) rather than a new, separate code path.
+  // This keeps real, already-observed status/timing/latency data while
+  // blanking BOTH bodies, so nothing downstream ever sees a response body
+  // that was never actually captured — honest degradation, never a
+  // fabrication. Unlike a genuine single-side overflow (where the OTHER
+  // side is still trustworthy), an expiry means the call's own completion
+  // state is unknown, so neither side is trusted here, deliberately. A
+  // silent drop (mirroring abort()) was considered and rejected: it would
+  // erase a real, timed, real-status call from spend forensics entirely,
+  // which is worse for a cost tool than a metadata-only row.
+  //
+  // unref()'d so this timer can NEVER keep a short-lived script or CLI
+  // process alive on its own — a preload that prevents process exit is
+  // itself the class of app-behavior change this whole file exists to
+  // avoid (see tests/observation_lifetime_timeout.rs).
+  const lifetimeTimer = setTimeout(() => {
+    try {
+      requestTruncated = true;
+      responseTruncated = true;
+      finish();
+    } catch {
+      /* fail open */
+    }
+  }, OBSERVATION_MAX_LIFETIME_MS);
+  lifetimeTimer.unref();
+
+  return {
+    setStatus(s) {
+      status = s;
+    },
+    appendRequest(chunk) {
+      requestChunks = append(chunk, requestChunks, "request");
+    },
+    appendResponse(chunk) {
+      responseChunks = append(chunk, responseChunks, "response");
+    },
+    finish,
+    abort,
+  };
+}
+
+// ─────────────────────────────────────────────────────── undici dispatcher
+
+// Measured this session (tasks/open-loops.md): the dispatcher Agent at this
+// symbol is created LAZILY, synchronously, as part of undici's OWN handling
+// of the first `fetch()` call in the process — a pre-installed
+// getter/setter trap on this symbol does NOT intercept that creation
+// (undici replaces the whole property descriptor via `Object.defineProperty`
+// rather than a plain assignment, confirmed by direct probe: a getter/setter
+// pair installed here beforehand simply never fires). The verified technique
+// is instead: force the dispatcher into existence with a harmless, ignored
+// WARM-UP fetch() call at install time (this file runs before any app code,
+// so this happens before the app's own first fetch), then mutate the
+// resulting Agent's `.dispatch` method IN PLACE. Because the Agent instance
+// is reused for the process lifetime, every subsequent fetch — including
+// the application's very first — dispatches through the wrapped method.
+const DISPATCHER_SYMBOL = Symbol.for("undici.globalDispatcher.1");
+
+function wrapDispatcher(agent) {
+  try {
+    if (!agent || typeof agent.dispatch !== "function" || agent.__culpaWrapped) {
+      return agent;
+    }
+    const originalDispatch = agent.dispatch.bind(agent);
+    agent.dispatch = function (opts, handler) {
+      try {
+        const observation = beginDispatchObservation(opts);
+        if (!observation) return originalDispatch(opts, handler);
+        return originalDispatch(opts, tapHandler(handler, observation));
+      } catch {
+        // fail open: any error while SETTING UP the observation falls back
+        // to the exact unwrapped call — zero behavior change either way
+        return originalDispatch(opts, handler);
+      }
+    };
+    agent.__culpaWrapped = true;
+    return agent;
+  } catch {
+    return agent; // fail open — return the agent unwrapped rather than throw
+  }
+}
+
+function beginDispatchObservation(opts) {
+  if (!opts) return null;
+  const origin = typeof opts.origin === "string" ? opts.origin : String(opts.origin ?? "");
+  const path = typeof opts.path === "string" ? opts.path : "";
+  const observation = newObservation(origin + path);
+  if (!observation) return null;
+  // Best-effort only: a fetch() body reaches undici's dispatch options as a
+  // stream in the general case, not the plain string the caller passed to
+  // fetch() — teeing a live request stream here would risk altering app
+  // behavior (exactly what is forbidden), so only the plain string/Buffer
+  // case is captured; anything else is silently skipped (usage tokens come
+  // from the RESPONSE body, which is always captured below regardless).
+  const bodyBuf = toBuffer(opts.body);
+  if (bodyBuf) observation.appendRequest(bodyBuf);
+  return observation;
+}
+
+/**
+ * A Proxy that forwards every call to the ORIGINAL handler unchanged
+ * (including its return value — undici's onData return value signals
+ * backpressure and must never be altered), while also feeding onHeaders/
+ * onData/onComplete/onError to the bounded observation buffer. This IS the
+ * tee: the app's own response is byte-identical either way (verified this
+ * session: `await r.json()` returned the body byte-intact through this
+ * exact wrap).
+ */
+function tapHandler(handler, observation) {
+  return new Proxy(handler, {
+    get(target, prop, receiver) {
+      const original = Reflect.get(target, prop, receiver);
+      if (prop === "onHeaders" && typeof original === "function") {
+        return function (statusCode, headers, resume, statusText) {
+          try {
+            observation.setStatus(statusCode);
+          } catch {
+            /* fail open */
+          }
+          return original.call(target, statusCode, headers, resume, statusText);
+        };
+      }
+      if (prop === "onData" && typeof original === "function") {
+        return function (chunk) {
+          try {
+            observation.appendResponse(toBuffer(chunk));
+          } catch {
+            /* fail open */
+          }
+          return original.call(target, chunk);
+        };
+      }
+      if (prop === "onComplete" && typeof original === "function") {
+        return function (trailers) {
+          try {
+            observation.finish();
+          } catch {
+            /* fail open */
+          }
+          return original.call(target, trailers);
+        };
+      }
+      if (prop === "onError" && typeof original === "function") {
+        return function (err) {
+          try {
+            observation.abort();
+          } catch {
+            /* fail open */
+          }
+          return original.call(target, err);
+        };
+      }
+      if (typeof original === "function") {
+        return original.bind(target);
+      }
+      return original;
+    },
+  });
+}
+
+function installDispatcherHook() {
+  const originalFetch = globalThis.fetch;
+  if (typeof originalFetch !== "function") return; // no global fetch in this runtime — nothing to hook
+  try {
+    // The warm-up: target refused instantly on loopback (nothing ever binds
+    // port 1), ignored entirely — its only purpose is forcing undici to
+    // create+store the global dispatcher SYNCHRONOUSLY, before returning, so
+    // it can be wrapped here rather than missed on the app's first real call.
+    originalFetch("http://127.0.0.1:1/culpa-collector-warmup").catch(() => {});
+  } catch {
+    /* fail open — dispatcher hook simply won't engage this run */
+  }
+  try {
+    wrapDispatcher(globalThis[DISPATCHER_SYMBOL]);
+  } catch {
+    /* fail open */
+  }
+}
+
+// ──────────────────────────────────────────────────────────────── http/https
+
+/**
+ * CR-1 (PR #15 review): patches res's own `emit` so this tee observes
+ * data/end/aborted/error exactly when the APP's own consumption already
+ * causes those events to fire — NEVER by attaching a `data` listener here,
+ * which would itself switch the stream into flowing mode and start it
+ * (the previous version of this file did exactly that, and it silently
+ * drained the app's own response body — see tapHttpRequest's call site for
+ * the full rationale and tests/response_body_integrity.rs for the proof).
+ * If the app never reads the response, res.emit('data', …) never fires at
+ * all here, nothing is captured, and the stream stays paused: honest
+ * degradation, never a silent theft of the app's body.
+ */
+function tapResponseEmit(res, observation) {
+  const originalEmit = res.emit.bind(res);
+  res.emit = function (event, ...args) {
+    if (event === "data") {
+      try {
+        observation.appendResponse(toBuffer(args[0]));
+      } catch {
+        /* fail open */
+      }
+    } else if (event === "end") {
+      try {
+        observation.finish();
+      } catch {
+        /* fail open */
+      }
+    } else if (event === "aborted" || event === "error") {
+      try {
+        observation.abort();
+      } catch {
+        /* fail open */
+      }
+    }
+    return originalEmit(event, ...args);
+  };
+}
+
+/**
+ * tasks/open-loops.md: the Anthropic SDK (0.27.3) rides http.request
+ * directly, NOT global fetch — invisible to the dispatcher hook above.
+ * Wraps `.request` on both modules (verified this session: status + full
+ * response body observed via a 'response'/'data'/'end' tee while the
+ * caller's own read of the same response stayed intact).
+ */
+function tapHttpRequest(req) {
+  const observation = newObservation(`${req.protocol || "http:"}//${req.host || ""}${req.path || "/"}`);
+  if (!observation) return;
+
+  // Tee the OUTGOING request body: wrap write()/end() so every byte the app
+  // sends upstream is also captured, without changing what reaches the
+  // socket — the original write/end still run with the exact same
+  // arguments and the exact same return value.
+  const originalWrite = req.write.bind(req);
+  req.write = function (chunk, ...rest) {
+    try {
+      observation.appendRequest(toBuffer(chunk));
+    } catch {
+      /* fail open */
+    }
+    return originalWrite(chunk, ...rest);
+  };
+  const originalEnd = req.end.bind(req);
+  req.end = function (chunk, ...rest) {
+    if (chunk !== undefined && typeof chunk !== "function") {
+      try {
+        observation.appendRequest(toBuffer(chunk));
+      } catch {
+        /* fail open */
+      }
+    }
+    return originalEnd(chunk, ...rest);
+  };
+
+  req.on("response", (res) => {
+    try {
+      observation.setStatus(res.statusCode);
+    } catch {
+      /* fail open */
+    }
+    // CR-1 (PR #15 review): NEVER attach a `data` listener here — the
+    // previous version of this comment ("Passive tee only ... just observes
+    // bytes as they flow") was WRONG, and dangerously so: attaching `data`
+    // is what STARTS flowing mode, it does not merely observe it. See
+    // tapResponseEmit's own doc comment for the fix and
+    // tests/response_body_integrity.rs for the reproduction and proof.
+    tapResponseEmit(res, observation);
+  });
+  req.on("error", () => {
+    try {
+      observation.abort();
+    } catch {
+      /* fail open */
+    }
+  });
+  // CR-2 (PR #15 review): Node's http.ClientRequest fires 'close' as its one
+  // DOCUMENTED, always-fires terminal event, covering every way a request
+  // can end. Corrected claim (2026-08 review pass — the original wording
+  // here overstated what has actually been observed): on Node v20.19.6,
+  // direct probing across nine distinct abort paths (client-side
+  // destroy()/socket destroy()/AbortController abort, server-side resets
+  // before and after headers, res.destroy() from the client) found that
+  // 'error' on req (pre-response) or 'aborted'/'error' on res (post-
+  // response) already fires for every one of them, ahead of 'close' — see
+  // native/culpa-collector/tests/inflight_counter_leak.rs's module doc for
+  // the full probe list and results. So on this Node build, none of the
+  // probed paths currently rely on 'close' alone to free the slot.
+  // This handler stays in as defense-in-depth: unlike 'close', 'error' is
+  // NOT documented as firing on every abort path, on every Node version, on
+  // every platform — a future Node release or an abort path not yet probed
+  // could settle a request without 'error'/'aborted' firing at all, and
+  // only 'close' would catch it. abort() is idempotent (settle()'s
+  // `finished` guard), so keeping this handler costs nothing: it never
+  // double-decrements and never double-ships even when finish()/abort()
+  // already ran via the normal path above.
+  req.on("close", () => {
+    try {
+      observation.abort();
+    } catch {
+      /* fail open */
+    }
+  });
+}
+
+function patchHttpModule(mod) {
+  const original = mod.request;
+  mod.request = function (...args) {
+    const req = original.apply(mod, args);
+    try {
+      tapHttpRequest(req);
+    } catch {
+      /* fail open — the real request object is returned untouched either way */
+    }
+    return req;
+  };
+}
+
+function installHttpHooks() {
+  try {
+    patchHttpModule(http);
+  } catch {
+    /* fail open */
+  }
+  try {
+    patchHttpModule(https);
+  } catch {
+    /* fail open */
+  }
+}
+
+// ──────────────────────────────────────────────────────────────── install
+
+// Both hooks, unconditionally, each independently wrapped so a throw during
+// install of ONE can never prevent the other from installing, and can never
+// reach app startup either way (fail-open covers installation itself, not
+// just steady-state operation).
+try {
+  installDispatcherHook();
+} catch {
+  /* fail open */
+}
+try {
+  installHttpHooks();
+} catch {
+  /* fail open */
+}