cartethyia 2.5.3 → 2.5.6

package/src/observability/payload-capture.ts

@@ -3,20 +3,68 @@ import { DrizzleTelemetryStore } from "../persistence/stores/telemetry-store";
 import { prunePayloadFrames, writePayloadFrame } from "./payload-store";
 import { resolveTelemetryPayloadMaxBytes } from "../config/telemetry";
 import { preferencesReaderFor } from "../persistence/tenant-preferences";
-import type { TelemetryPayloadDepth, TelemetryPayloadMode } from "../console/settings/contracts";
+import type {
+  TelemetryPayloadDepth,
+  TelemetryPayloadMode,
+  TelemetryPayloadRetentionMinutes,
+} from "../console/settings/contracts";
 export type CaptureScope = "tenant" | "debug_session" | "operator_flag";
 
+/**
+ * How long a captured payload frame lives when the deployment has not chosen.
+ *
+ * Exported so surfaces that report on disk usage quote the same window the
+ * capture path enforces, rather than a second copy of the default that would
+ * drift the first time this one changes.
+ */
+export function payloadRetentionMs(): number {
+  const raw = Number(process.env.CARTETHYIA_TELEMETRY_PAYLOAD_RETENTION_MS ?? 15 * 60_000);
+  if (!Number.isFinite(raw) || raw < 1_000 || raw > MAX_PAYLOAD_RETENTION_MS) return 15 * 60_000;
+  return Math.floor(raw);
+}
+
+/**
+ * The longest payload retention a tenant may ask for: seven days.
+ *
+ * Two things depend on this being a hard ceiling rather than a suggestion.
+ *
+ * The prune pass deletes a frame file it cannot parse once the file's last
+ * write is older than the retention window — that bound is the only thing that
+ * makes a damaged file reclaimable at all. A tenant allowed to keep frames for
+ * a year while the prune assumed an hour would have live frames deleted out
+ * from under them.
+ *
+ * The disk-usage panel counts a frame as reclaimable once its file is older
+ * than the same window. Without a ceiling it would offer a reclaim button for
+ * frames that are still live, and the operator would press it and see
+ * "nothing to reclaim".
+ */
+export const MAX_PAYLOAD_RETENTION_MS = 7 * 24 * 60 * 60_000;
+
+/** Milliseconds one tenant's chosen retention resolves to. */
+export function retentionMsFor(minutes: number | null | undefined): number {
+  if (minutes === null || minutes === undefined) return payloadRetentionMs();
+  if (!Number.isFinite(minutes)) return payloadRetentionMs();
+  return Math.min(Math.max(1_000, Math.floor(minutes * 60_000)), MAX_PAYLOAD_RETENTION_MS);
+}
+
 /**
  * Settings-gated payload capture. Request-event metadata is always retained;
  * tenants opt into drawer capture through Settings → Privacy: `metadata`
  * keeps only the Proxy→Provider request line, `full` keeps redacted bodies
- * at the tenant's chosen depth. Fail-closed on error.
+ * at the tenant's chosen depth, and both live for the tenant's chosen
+ * retention. Fail-closed on error.
  */
 export async function resolvePayloadCapture(
   db: CartethyiaDatabase,
   tenantId: string | null,
 ): Promise<
-  | { readonly ok: true; readonly mode: TelemetryPayloadMode; readonly depth: TelemetryPayloadDepth }
+  | {
+      readonly ok: true;
+      readonly mode: TelemetryPayloadMode;
+      readonly depth: TelemetryPayloadDepth;
+      readonly retentionMs: number;
+    }
   | { readonly ok: false }
 > {
   if (!tenantId) return { ok: false };
@@ -24,6 +72,7 @@ export async function resolvePayloadCapture(
     const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
     const mode = prefs?.telemetryPayloads;
     const depth = prefs?.telemetryPayloadDepth;
+    const retention = prefs?.telemetryPayloadRetentionMinutes;
     return {
       ok: true,
       mode: mode === "full" || mode === "metadata" || mode === "none" ? mode : "none",
@@ -37,12 +86,13 @@ export async function resolvePayloadCapture(
               : depth === "full"
                 ? "maximum"
                 : "minimum",
+      retentionMs: retentionMsFor(retention as TelemetryPayloadRetentionMinutes | undefined),
     };
   } catch {
     // A preference read that fails must not invent capture. Off keeps nothing.
     // Reported as its own state rather than silently as `none`: an operator
     // whose capture is off by choice and one whose preference read is failing
-    // need different fixes, and both used to look like "not configured".
+    // need different fixes, and both would otherwise look like "not configured".
     return { ok: false };
   }
 }
@@ -99,6 +149,12 @@ export interface PayloadCaptureInput {
    * Defaults to the configured capture limit.
    */
   maxBytes?: number;
+  /**
+   * How long this frame lives, in ms. Defaults to the tenant's chosen
+   * retention, then the deployment default. Bounded by
+   * {@link MAX_PAYLOAD_RETENTION_MS} either way.
+   */
+  retentionMs?: number;
   scope: CaptureScope;
   /** Links the row to `telemetry_events.request_id`. */
   requestId?: string;
@@ -140,11 +196,13 @@ export interface StoredPayload {
   signals: PayloadSignals;
 }
 
-function payloadRetentionMs(): number {
-  const raw = Number(process.env.CARTETHYIA_TELEMETRY_PAYLOAD_RETENTION_MS ?? 15 * 60_000);
-  if (!Number.isFinite(raw) || raw < 1_000 || raw > 7 * 24 * 60 * 60_000) return 15 * 60_000;
-  return Math.floor(raw);
-}
+/**
+ * How long a captured payload frame lives.
+ *
+ * Exported so surfaces that report on disk usage quote the same window the
+ * capture path enforces, rather than a second copy of the default that would
+ * drift the first time this one changes.
+ */
 function isCaptureAllowed(input: PayloadCaptureInput): boolean {
   // Exactly one opt-in must be set, and it must be the one `scope` names:
   // two flags at once would silently widen capture beyond the declared scope.
@@ -202,28 +260,29 @@ function payloadSignals(values: readonly unknown[]): PayloadSignals {
  * `maxBytes` (post-redaction, defaulting to the configured capture limit): a
  * body that no longer fits is replaced with a truncation marker — no object
  * store exists, so an oversized body is never referenced, only accounted.
- * Payloads remain redacted and bounded during the 15-minute retention window.
+ * Payloads remain redacted and bounded during their retention window.
  *
  * Drawer order is the allocation order, and that is deliberate: the cap is a
  * single shared budget, so whatever is accounted first is what survives a
  * large request. `response_body` is the legacy alias of the client response
- * and names no panel of its own, so it is accounted **last** — while it was
- * second, a large client request plus its own duplicate consumed the whole
- * budget before the Provider Request and Provider Response panels were
- * reached, and those two read empty for a request that did reach an upstream.
+ * and names no panel of its own, so it is accounted **last** — accounting it
+ * earlier lets a large client request plus its own duplicate consume the whole
+ * budget before the Provider Request and Provider Response panels are reached,
+ * and those two then read empty for a request that did reach an upstream.
  */
 export function buildPayloadRecord(
   input: PayloadCaptureInput,
   now = new Date(),
   maxBytes = resolveTelemetryPayloadMaxBytes(),
+  retentionMs = payloadRetentionMs(),
 ): Omit<StoredPayload, "id"> {
-  const expiresAt = new Date(now.getTime() + payloadRetentionMs());
+  const expiresAt = new Date(now.getTime() + retentionMs);
   // Each body is serialized once, in drawer order, and only while the running
-  // total still fits the cap. The old path serialized every body up front to
-  // measure them and then serialized the whole record again to store it, so a
-  // capture held two copies of every body at once — measured at 23 MB of heap
-  // for 8 MB of bodies. A body that would cross the cap is never touched: its
-  // text is not built and its object is not walked for signals.
+  // total still fits the cap. Serializing every body up front to measure them
+  // and then serializing the whole record again to store it holds two copies of
+  // every body at once — measured at 23 MB of heap for 8 MB of bodies. A body
+  // that would cross the cap is never touched: its text is not built and its
+  // object is not walked for signals.
   const surfaces: ReadonlyArray<readonly [keyof StoredPayload, unknown]> = [
     ["request_body", input.requestBody],
     ["provider_request_body", input.providerRequestBody],
@@ -263,11 +322,11 @@ export function buildPayloadRecord(
     serialized.push(text);
     kept.push(body);
   }
-  // Only a surface that *had* a body and lost it to the cap is marked. The
-  // previous form stamped the marker onto every null surface, including ones
-  // that never carried anything — a request that never reached an upstream
-  // then reported "truncated" for a provider panel that was never captured,
-  // and the stage bitmask counted a marker as captured content.
+  // Only a surface that *had* a body and lost it to the cap is marked.
+  // Stamping the marker onto every null surface would also mark surfaces that
+  // never carried anything — a request that never reached an upstream then
+  // reports "truncated" for a provider panel that was never captured, and the
+  // stage bitmask counts a marker as captured content.
   const marker = (originalBytes: number): unknown => ({
     _truncated: true,
     _original_bytes: originalBytes,
@@ -303,14 +362,26 @@ export function buildPayloadRecord(
 }
 
 /**
- * Postgres-backed redacted request/response payload capture. Payloads have a
- * 15-minute retention window and are automatically pruned.
+ * Postgres-backed redacted request/response payload capture. Payloads live for
+ * the tenant's chosen retention — 15 minutes by default — and are pruned by the
+ * sweep.
 
  */
 export class TelemetryPayloadCapture {
   private readonly store: DrizzleTelemetryStore;
 
-  constructor(db: CartethyiaDatabase) {
+  constructor(
+    db: CartethyiaDatabase,
+    /**
+     * Reads the tenant's chosen retention for captures that arrive without one.
+     *
+     * Injected rather than imported so the capture path does not depend on the
+     * console's settings module, and so a test can pin a retention without
+     * touching the database. Absent means every capture uses the deployment
+     * default, which is what a probe or a debug session wants anyway.
+     */
+    private readonly retentionFor?: (tenantId: string) => Promise<number> | number,
+  ) {
     this.store = new DrizzleTelemetryStore(db);
   }
 
@@ -320,7 +391,17 @@ export class TelemetryPayloadCapture {
         code: "capture_not_opted_in",
       });
     }
-    const record = buildPayloadRecord(input, new Date(), input.maxBytes ?? resolveTelemetryPayloadMaxBytes());
+    // A caller that knows the answer passes it; otherwise the tenant's own
+    // preference is resolved, and failing that the deployment default. The
+    // early-rejection path has no preference to hand and lands here, which is
+    // why the default must be the deployment one rather than the shortest.
+    const retentionMs = await resolveRetention(input, this.retentionFor);
+    const record = buildPayloadRecord(
+      input,
+      new Date(),
+      input.maxBytes ?? resolveTelemetryPayloadMaxBytes(),
+      retentionMs,
+    );
     const reference = await writePayloadFrame(record, record.expires_at, record._serialized
       ? {
           requestId: record.request_id,
@@ -357,10 +438,54 @@ export class TelemetryPayloadCapture {
       deleted += batch;
       if (batch < batchSize) break;
     }
-    // Every frame expires `payloadRetentionMs()` after it is written, so a file
-    // last written before that window closed cannot still hold a live frame.
-    // That bound is what makes a damaged, unparsable file reclaimable at all.
-    deleted += await prunePayloadFrames(now, new Date(now.getTime() - payloadRetentionMs()));
+    // A file last written before *the longest retention a tenant can choose*
+    // closed cannot still hold a live frame — whatever its tenant picked, that
+    // frame has expired. Using the deployment default here instead was correct
+    // only while every frame shared one window: with a tenant allowed to keep
+    // frames for a week, a 15-minute bound would delete files still holding
+    // frames their rows address, and the drawer would silently read empty.
+    deleted += await prunePayloadFrames(now, payloadPruneBound(now));
     return { deleted };
   }
 }
+
+/**
+ * The cutoff before which a frame file can be deleted wholesale.
+ *
+ * Every frame expires at most {@link MAX_PAYLOAD_RETENTION_MS} after it is
+ * written, so a file last touched before that instant cannot still hold a live
+ * frame — and that is the only thing that makes a damaged, unparsable file
+ * reclaimable at all. Exported so the bound is pinned without a database: the
+ * alternative is a test that deletes a live frame and notices nothing.
+ */
+export function payloadPruneBound(now: Date): Date {
+  return new Date(now.getTime() - MAX_PAYLOAD_RETENTION_MS);
+}
+
+/**
+ * How long one capture's frame should live.
+ *
+ * Order of authority: the caller's own value, then the tenant's preference,
+ * then the deployment default. A failure resolving the tenant's preference
+ * falls back rather than throwing — an unknown retention must not turn into a
+ * lost capture, and the deployment default is always a valid answer.
+ */
+export async function resolveRetention(
+  input: PayloadCaptureInput,
+  retentionFor?: (tenantId: string) => Promise<number> | number,
+): Promise<number> {
+  if (typeof input.retentionMs === "number" && Number.isFinite(input.retentionMs)) {
+    return Math.min(Math.max(1_000, Math.floor(input.retentionMs)), MAX_PAYLOAD_RETENTION_MS);
+  }
+  if (retentionFor) {
+    try {
+      const value = await retentionFor(input.tenantId);
+      if (Number.isFinite(value)) {
+        return Math.min(Math.max(1_000, Math.floor(value)), MAX_PAYLOAD_RETENTION_MS);
+      }
+    } catch {
+      // Falls through to the deployment default below.
+    }
+  }
+  return payloadRetentionMs();
+}

package/src/observability/payload-store.ts

@@ -4,12 +4,7 @@ import { randomUUID } from "node:crypto";
 import { gunzipSync, gzipSync } from "node:zlib";
 
 export interface PayloadFileReference {
-  /**
-   * `jsonb-file` is a frame written before compression existed: plain JSON.
-   * New frames are `jsonl-file`: the same JSON, gzipped. The row names its
-   * encoding, so a reader never guesses and an old row still resolves.
-   */
-  readonly storage: "jsonb-file" | "jsonl-file";
+  readonly storage: "jsonl-file";
   readonly file: string;
   readonly offset: number;
   readonly length: number;
@@ -28,7 +23,7 @@ export function isPayloadFileReference(value: unknown): value is PayloadFileRefe
   if (typeof value !== "object" || value === null) return false;
   const record = value as Record<string, unknown>;
   return (
-    (record["storage"] === "jsonb-file" || record["storage"] === "jsonl-file") &&
+    record["storage"] === "jsonl-file" &&
     typeof record["file"] === "string" &&
     typeof record["offset"] === "number" &&
     typeof record["length"] === "number" &&
@@ -62,7 +57,13 @@ export function payloadReferenceFromRow(row: {
   return isPayloadFileReference(candidate) ? candidate : undefined;
 }
 
-const FRAME_HEADER_BYTES = 4;
+/** Extension for frame files. */
+const FRAME_FILE_SUFFIX = ".jsonl";
+
+function isFrameFileName(name: string): boolean {
+  return name.endsWith(FRAME_FILE_SUFFIX);
+}
+
 const MAX_FRAME_BYTES = 256 * 1024 * 1024;
 const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
 const DEFAULT_DIRECTORY = "./data/telemetry-payloads";
@@ -96,7 +97,7 @@ function checksum(value: Buffer | readonly Buffer[]): string {
 }
 
 function fileName(now = new Date()): string {
-  return `${now.toISOString().slice(0, 13).replaceAll(":", "-")}-${process.pid}.jsonb`;
+  return `${now.toISOString().slice(0, 13).replaceAll(":", "-")}-${process.pid}${FRAME_FILE_SUFFIX}`;
 }
 
 /**
@@ -115,34 +116,50 @@ function compressFrame(parts: readonly Buffer[]): Buffer {
 async function appendFrame(frame: PayloadFrame, parts?: readonly Buffer[]): Promise<PayloadFileReference> {
   const directory = payloadDirectory();
   await mkdir(directory, { recursive: true });
-  parts ??= [Buffer.from(JSON.stringify(frame), "utf8")];
-  const encoded = compressFrame(parts);
-  if (encoded.byteLength > MAX_FRAME_BYTES) throw new Error("telemetry payload frame exceeds limit");
+  // Encoded as a line here rather than at the write, so the cap, the checksum,
+  // and the reference all describe the same bytes that land on disk — the
+  // prebuilt-parts path and the plain one cannot disagree about the shape.
+  const json = parts === undefined
+    ? Buffer.from(JSON.stringify(frame), "utf8")
+    : Buffer.concat(parts);
+  const compressed = compressFrame([json]);
+  if (compressed.byteLength > MAX_FRAME_BYTES) throw new Error("telemetry payload frame exceeds limit");
+  const encoded = toLine(compressed);
   const file = fileName();
   const path = join(directory, file);
   const currentSize = await stat(path).then((value) => value.size).catch(() => 0);
   const offset = currentSize;
-  if (offset + FRAME_HEADER_BYTES + encoded.byteLength > maxFileBytes()) {
-    const rotated = `${Date.now()}-${randomUUID()}.jsonb`;
-    return appendFrameToPath(frame, join(directory, rotated), basename(rotated), undefined, encoded);
+  if (offset + encoded.byteLength > maxFileBytes()) {
+    const rotated = `${Date.now()}-${randomUUID()}${FRAME_FILE_SUFFIX}`;
+    return appendFrameToPath(join(directory, rotated), encoded, basename(rotated));
   }
-  return appendFrameToPath(frame, path, file, offset, encoded);
+  return appendFrameToPath(path, encoded, file, offset);
+}
+
+/**
+ * One frame as a stored line: base64 of the gzipped JSON, newline-terminated.
+ *
+ * A newline is the frame delimiter, so the file is a text file of base64 lines
+ * and a frame's extent is found by reading to the next `\n` — a binary length
+ * header would make every frame opaque, unreadable without first decoding a
+ * big-endian length and then gunzipping exactly that many bytes.
+ *
+ * base64 rather than raw gzip bytes because gzip contains newlines, which
+ * would make the delimiter ambiguous.
+ */
+function toLine(compressed: Buffer): Buffer {
+  return Buffer.from(`${compressed.toString("base64")}\n`, "utf8");
 }
 
 async function appendFrameToPath(
-  frame: PayloadFrame,
   path: string,
+  encoded: Buffer,
   knownFile = basename(path),
   knownOffset?: number,
-  knownEncoded?: Buffer,
 ): Promise<PayloadFileReference> {
-  const encoded = knownEncoded ?? compressFrame([Buffer.from(JSON.stringify(frame), "utf8")]);
   const offset = knownOffset ?? await stat(path).then((value) => value.size).catch(() => 0);
-  const header = Buffer.alloc(FRAME_HEADER_BYTES);
-  header.writeUInt32BE(encoded.byteLength, 0);
   const handle = await open(path, "a");
   try {
-    await handle.write(header);
     await handle.write(encoded);
   } finally {
     await handle.close();
@@ -151,7 +168,7 @@ async function appendFrameToPath(
     storage: "jsonl-file",
     file: knownFile,
     offset,
-    length: FRAME_HEADER_BYTES + encoded.byteLength,
+    length: encoded.byteLength,
     checksum: checksum(encoded),
     version: 1,
   };
@@ -166,6 +183,11 @@ async function appendFrameToPath(
  * drawer order with the legacy `response_body` alias last, for the same reason
  * the record accounts it last: it names no panel of its own and must not
  * spend the shared byte budget ahead of the provider stages.
+ *
+ * There are five, not four. `buildPayloadRecord` builds one string per surface
+ * and `response_body` is the fifth — dropping it here wrote the frame with the
+ * first four bodies and silently discarded the last, so a capture whose client
+ * response was in the legacy slot came back with that panel empty.
  */
 const FRAME_BODY_KEYS = [
   "request_body",
@@ -240,14 +262,7 @@ export async function readPayloadFrame(reference: PayloadFileReference): Promise
     await handle.close();
   }
   const frame = data;
-  const length = frame.readUInt32BE(0);
-  if (length <= 0 || length + FRAME_HEADER_BYTES !== frame.byteLength) return undefined;
-  const stored = frame.subarray(FRAME_HEADER_BYTES);
-  if (checksum(stored) !== reference.checksum) return undefined;
-  // The row says which encoding it wrote. A compressed row that does not
-  // decompress is a damaged frame, reported as absent like any other
-  // unreadable frame, never thrown into the request that asked for it.
-  const json = reference.storage === "jsonl-file" ? gunzipFrame(stored) : stored;
+  const json = frameJsonFromSlice(frame);
   if (json === undefined) return undefined;
   const parsed = JSON.parse(json.toString("utf8")) as PayloadFrame;
   return parsed.version === 1 ? parsed.payload : undefined;
@@ -262,6 +277,24 @@ function gunzipFrame(stored: Buffer): Buffer | undefined {
   }
 }
 
+/**
+ * The JSON of one frame read out of a file.
+ *
+ * A frame is a base64 line — base64 because gzip contains newlines, which would
+ * make the newline delimiter ambiguous. The bytes are gunzipped only if they
+ * are gzip; `gunzipFrame` returning `undefined` is what marks a slice as not a
+ * frame.
+ */
+function frameJsonFromSlice(
+  slice: Buffer,
+): Buffer | undefined {
+  // Frames are a base64 line. The trailing newline is not part of the payload.
+  const text = slice.toString("utf8").trim();
+  if (text.length === 0) return undefined;
+  const gzipped = Buffer.from(text, "base64");
+  return gunzipFrame(gzipped);
+}
+
 /**
  * What a whole file's parseable frames say about reclaiming it.
  *
@@ -272,40 +305,25 @@ function gunzipFrame(stored: Buffer): Buffer | undefined {
  */
 type FrameLiveness = "live" | "none" | "unknown";
 
-/**
- * The JSON of one stored frame, whichever encoding wrote it.
- *
- * A frame names no encoding of its own — the row does — and this pass reads
- * files, not rows. gzip bytes start with the 0x1f 0x8b magic and plain JSON
- * starts with `{`, so the encoding is read off the bytes. Anything else is
- * corrupt and falls through to the caller's parse, which reports the file
- * unreadable rather than empty.
- */
-function frameJson(stored: Buffer): Buffer {
-  if (stored.byteLength >= 2 && stored[0] === 0x1f && stored[1] === 0x8b) {
-    return gunzipSync(stored);
-  }
-  return stored;
-}
-
-
 function frameLiveness(data: Buffer, before: Date): FrameLiveness {
   let offset = 0;
-  while (offset + FRAME_HEADER_BYTES <= data.byteLength) {
-    const length = data.readUInt32BE(offset);
-    const end = offset + FRAME_HEADER_BYTES + length;
-    // A length that runs past the file is a half-written tail, not a frame.
-    if (length <= 0 || end > data.byteLength) return "unknown";
+  while (offset < data.byteLength) {
+    const newline = data.indexOf(0x0a, offset);
+    if (newline <= 0) return "unknown";
+    const end = newline + 1;
+    const slice = data.subarray(offset, end);
+    const json = frameJsonFromSlice(slice);
+    if (json === undefined) return "unknown";
     let frame: PayloadFrame;
     try {
-      frame = JSON.parse(frameJson(data.subarray(offset + FRAME_HEADER_BYTES, end)).toString("utf8")) as PayloadFrame;
+      frame = JSON.parse(json.toString("utf8")) as PayloadFrame;
     } catch {
       return "unknown";
     }
     if (new Date(frame.expiresAt).getTime() >= before.getTime()) return "live";
     offset = end;
   }
-  // Bytes left over that are too short to hold a header are an unreadable tail.
+  // Bytes left over that are too short to hold a frame are an unreadable tail.
   return offset === data.byteLength ? "none" : "unknown";
 }
 
@@ -327,10 +345,11 @@ function frameLiveness(data: Buffer, before: Date): FrameLiveness {
  * supply that bound leaves the default, which keeps damaged files rather than
  * risk dropping a frame a row still addresses.
  *
- * One damaged file must not abort the pass. A single corrupt frame used to
- * throw straight out of the loop, so every other expired file stayed on disk
- * forever and the volume only grew — and because a container restart is the
- * usual way a half-written tail appears, the failure looked Docker-specific.
+ * One damaged file must not abort the pass. If a single corrupt frame threw
+ * straight out of the loop, every other expired file would stay on disk
+ * forever and the volume would only grow — and because a container restart is
+ * the usual way a half-written tail appears, the failure would look
+ * Docker-specific.
  */
 export async function prunePayloadFrames(
   before: Date,
@@ -340,7 +359,7 @@ export async function prunePayloadFrames(
   const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
   let deleted = 0;
   for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith(".jsonb")) continue;
+    if (!entry.isFile() || !isFrameFileName(entry.name)) continue;
     const path = join(directory, entry.name);
     try {
       if (await fileReclaimable(path, before, unparseableWrittenBefore)) {
@@ -367,7 +386,9 @@ async function fileReclaimable(
   unparseableWrittenBefore: Date,
 ): Promise<boolean> {
   const data = await readFile(path);
-  if (data.byteLength < FRAME_HEADER_BYTES) return true;
+  // Nothing written yet, so nothing to lose. A real frame is far longer than
+  // any header this format could carry.
+  if (data.byteLength === 0) return true;
   const liveness = frameLiveness(data, before);
   if (liveness === "live") return false;
   if (liveness === "none") return true;

package/src/observability/redaction.ts

@@ -1,13 +1,12 @@
 // Client-IP presentation masking.
 //
-// This module used to also carry a telemetry redactor that rewrote any string
-// containing a credential-shaped token into a placeholder. It was meant for
-// display, but `***REDACTED***` in a captured body is indistinguishable from
+// This module carries no string-sniffing payload redactor, and must not grow
+// one: `***REDACTED***` in a captured body is indistinguishable from
 // `***REDACTED***` in a payload that was actually sent — so a memory-review
-// turn quoting one JWT rendered as a fully redacted message, and a 400 from
-// the provider looked like the gateway had mangled the request.
+// turn quoting one JWT would render as a fully redacted message, and a 400 from
+// the provider would look like the gateway had mangled the request.
 //
-// Payload bodies are stored verbatim now. The upstream already refuses and
+// Payload bodies are stored verbatim. The upstream already refuses and
 // reports credentials on its own; a second, string-sniffing layer only
 // destroys the evidence needed to read a failure.
 

package/src/observability/request-notify.ts

@@ -0,0 +1,43 @@
+/**
+ * Lightweight fan-out for completed gateway requests.
+ *
+ * `notifyRequestCompleted` is called once per terminal request (same site as
+ * `telemetryBuffer.enqueue`). Subscribers receive a minimal summary — just
+ * enough for the dashboard SSE stream to trigger a targeted refetch rather
+ * than polling.
+ */
+
+export interface RequestCompletedNotice {
+  readonly tenantId: string;
+  readonly requestId: string;
+  readonly status: string;
+  readonly httpStatus: number;
+}
+
+type Listener = (notice: RequestCompletedNotice) => void;
+
+const listeners = new Set<Listener>();
+
+/** Notify all subscribers that a request has reached a terminal state. */
+export function notifyRequestCompleted(notice: RequestCompletedNotice): void {
+  for (const listener of listeners) {
+    try {
+      listener(notice);
+    } catch {
+      // Listener failures must not affect the request path.
+    }
+  }
+}
+
+/** Subscribe to per-request terminal notifications; returns unsubscribe. */
+export function subscribeRequestCompleted(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only: clear all subscribers. */
+export function resetRequestNotifyForTests(): void {
+  listeners.clear();
+}

package/src/observability/telemetry-status.ts

@@ -1,13 +1,12 @@
 /**
  * The single definition of which requests count as *gateway* errors.
  *
- * Six independent sites used to answer this question with their own copy of
- * `status in ('failed', 'truncated')`: the usage summary, the health window,
- * the usage breakdown, the retained-usage rollup (`telemetry_usage_totals`),
- * the public share page, and the client-IP breakdown. A definition spread over
- * six predicates is not a definition — it is six chances to drift, and the
- * rollup made the drift durable: once a request is counted into
- * `telemetry_usage_totals.errors` it stays counted after the raw row is pruned.
+ * One definition keeps the six sites that ask this — the usage summary, the
+ * health window, the usage breakdown, the retained-usage rollup
+ * (`telemetry_usage_totals`), the public share page, and the client-IP
+ * breakdown — from drifting apart, which matters because the rollup makes any
+ * drift durable: once a request is counted into `telemetry_usage_totals.errors`
+ * it stays counted after the raw row is pruned.
  *
  * The rule, stated as a principle rather than a list of codes:
  *
@@ -23,8 +22,8 @@
  *   an unregistered `/v1/*` path, a `429` from the caller's own quota, and a
  *   `413` from an oversized body all cost the sender nothing and reach no
  *   provider, so counting any of them hands an abuser a free way to inflate
- *   the error rate. Enumerating "the bad ones" was the previous approach and it
- *   missed `401`/`429`; excluding the class cannot miss one.
+ *   the error rate. Enumerating "the bad ones" misses `401`/`429`; excluding the
+ *   class cannot miss one.
  * - **`499`** is a client abort (`transport_closed`). The client leaving is
  *   expected behavior — the request may even have been served — and it is
  *   tracked as its own count. Being below `500`, it is excluded by the class

package/src/observability/token-speed.ts

@@ -51,10 +51,11 @@ export interface TokenSpeedInput {
 export function computeTokensPerSec(input: TokenSpeedInput): number | undefined {
   const outputTokens = input.outputTokens;
   // `!Number.isFinite` rather than `<= 0`: a NaN token count fails `NaN <= 0`
-  // (`false`), so it used to pass through and the division produced a NaN speed —
-  // which reaches the telemetry row and renders as a literal "NaN tok/s" in the
-  // Requests table. That is the case where a wrong number is least welcome, since
-  // the row that produced it is the one an operator is investigating.
+  // (`false`), so it would pass through and the division would produce a NaN
+  // speed — which reaches the telemetry row and renders as a literal
+  // "NaN tok/s" in the Requests table. That is the case where a wrong number is
+  // least welcome, since the row that produced it is the one an operator is
+  // investigating.
   if (outputTokens === undefined || !Number.isFinite(outputTokens) || outputTokens <= 0) {
     return undefined;
   }