cartethyia 2.5.9 → 2.6.0

package/src/observability/log-ring.ts

@@ -4,6 +4,7 @@
  * snapshot and then subscribes over SSE (`console/observability/logs.ts`); nothing
  * here touches the database — restarts clear the tail by design.
  */
+import { sanitizeLogValue } from './log-sanitize';
 
 export const CONSOLE_LOG_LEVELS = ["debug", "info", "warn", "error"] as const;
 
@@ -53,6 +54,19 @@ export interface ConsoleLogMetadata {
   readonly details?: Record<string, unknown>;
 }
 
+/**
+ * Bounds one structured `details` object.
+ *
+ * Returns a fresh record rather than mutating, so a caller that keeps its own
+ * reference to the object it passed does not find it rewritten.
+ */
+function sanitizeLogDetails(details: Record<string, unknown>): Record<string, unknown> {
+  const sanitized = sanitizeLogValue(details);
+  return typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)
+    ? (sanitized as Record<string, unknown>)
+    : {};
+}
+
 export function pushStructuredConsoleLog(
   level: ConsoleLogLevel,
   msg: string,
@@ -67,8 +81,12 @@ export type ConsoleLogEvent =
   | { readonly type: "line"; readonly line: ConsoleLogLine }
   | { readonly type: "clear" };
 
-const CAPACITY = 500;
-const MAX_MSG = 2_000;
+/** Lines retained. Exported so the console can state the tail's depth. */
+export const CONSOLE_LOG_CAPACITY = 500;
+/** Code units kept per rendered message. Exported for the same reason. */
+export const CONSOLE_LOG_MAX_MESSAGE_CODE_UNITS = 2_000;
+const CAPACITY = CONSOLE_LOG_CAPACITY;
+const MAX_MSG = CONSOLE_LOG_MAX_MESSAGE_CODE_UNITS;
 
 const lines: ConsoleLogLine[] = [];
 // Start index of the live window: eviction advances the pointer instead of
@@ -82,6 +100,12 @@ function appendLine(line: Omit<ConsoleLogLine, "ts" | "msg"> & { readonly msg: s
     ts: new Date().toISOString(),
     ...line,
     msg: line.msg.length > MAX_MSG ? `${line.msg.slice(0, MAX_MSG)}…` : line.msg,
+    // `details` is caller-supplied and never routed through the logger, so it
+    // is the one field that could arrive unbounded: a structured line carrying
+    // a whole response body would make this 500-line ring hold a fraction of
+    // one event. Bounded by the same sanitizer the logger uses, so the two
+    // paths cannot disagree about what "bounded" means.
+    ...(line.details === undefined ? {} : { details: sanitizeLogDetails(line.details) }),
   };
   lines.push(stored);
   if (lines.length - ringStart > CAPACITY) ringStart += 1;

package/src/observability/log-sanitize.ts

@@ -0,0 +1,118 @@
+/**
+ * Bounded structural sanitization for log payloads.
+ *
+ * Its own module because both directions need it: `logger.ts` bounds what it
+ * hands Pino and the console ring, and `log-ring.ts` bounds structured
+ * `details` pushed by callers that never go through the logger. Putting it in
+ * either one would be an import cycle.
+ *
+ * Depth alone does not bound a log payload. A single multi-megabyte string
+ * field passes any depth cap, and so does an array of ten thousand short
+ * items — either is copied in full on the request path, and a log call that
+ * allocates megabytes to describe an error makes the error worse. Every
+ * dimension gets a cap, and every marker is the same stable `[truncated]` so a
+ * bounded line is recognizable as bounded rather than looking like content.
+ */
+
+/** Nesting levels kept. */
+export const LOG_MAX_DEPTH = 5;
+/** Array elements kept per array. */
+export const LOG_MAX_ARRAY_ITEMS = 32;
+/** Object keys kept per object. */
+export const LOG_MAX_KEYS = 64;
+/** Code units kept per string. */
+export const LOG_MAX_STRING_CODE_UNITS = 4_096;
+/**
+ * Total nodes visited per copy.
+ *
+ * The whole-copy cap, and the one that actually stops a wide graph: depth and
+ * the per-container limits bound each dimension, but a million sibling keys at
+ * depth 2 passes all of them.
+ */
+export const LOG_MAX_NODES = 256;
+
+/** Code units kept when rendering one console-ring line. */
+export const LOG_RING_MAX_CODE_UNITS = 8_192;
+
+/** Marker appended wherever content was dropped. */
+export const LOG_TRUNCATED_MARKER = "[truncated]";
+export const LOG_CIRCULAR_MARKER = "[circular]";
+
+function isHighSurrogate(code: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff;
+}
+
+/**
+ * Truncates without splitting a surrogate pair.
+ *
+ * Cutting between a high and low surrogate leaves a lone half, which renders
+ * as U+FFFD — a log line that looks like the data was corrupt rather than
+ * merely cut short.
+ */
+export function truncateLogString(value: string, maxCodeUnits: number): string {
+  if (value.length <= maxCodeUnits) return value;
+  const end =
+    maxCodeUnits > 0 && isHighSurrogate(value.charCodeAt(maxCodeUnits - 1))
+      ? maxCodeUnits - 1
+      : maxCodeUnits;
+  return `${value.slice(0, end)}${LOG_TRUNCATED_MARKER}`;
+}
+
+/**
+ * A circular-safe, bounded copy.
+ *
+ * Cycle-guarded because the canonical redactor applied downstream recurses
+ * without one: a circular log arg would overflow the stack before redaction
+ * ran. Errors collapse to name+message — a stack is far too long for a tail
+ * line, and the message already carries the cause.
+ *
+ * The node budget is a mutable counter object rather than a returned value:
+ * a recursive walk that threaded remaining budget through every branch would
+ * silently unbound any subtree that forgot to pass it along.
+ */
+export function sanitizeLogValue(value: unknown): unknown {
+  return decycle(value, { remaining: LOG_MAX_NODES }, new WeakSet(), 0);
+}
+
+function decycle(
+  value: unknown,
+  budget: { remaining: number },
+  seen: WeakSet<object>,
+  depth: number,
+): unknown {
+  if (typeof value === "string") return truncateLogString(value, LOG_MAX_STRING_CODE_UNITS);
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return LOG_CIRCULAR_MARKER;
+  if (depth > LOG_MAX_DEPTH) return LOG_TRUNCATED_MARKER;
+  if (budget.remaining <= 0) return LOG_TRUNCATED_MARKER;
+  budget.remaining -= 1;
+  if (value instanceof Error) {
+    return {
+      name: truncateLogString(value.name, LOG_MAX_STRING_CODE_UNITS),
+      message: truncateLogString(value.message, LOG_MAX_STRING_CODE_UNITS),
+    };
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const kept = value
+      .slice(0, LOG_MAX_ARRAY_ITEMS)
+      .map((item) => decycle(item, budget, seen, depth + 1));
+    // The count is the point of a log line: "200 items, first 32 shown" reads
+    // very differently from "32 items".
+    if (value.length > LOG_MAX_ARRAY_ITEMS) {
+      kept.push(`[truncated:${value.length - LOG_MAX_ARRAY_ITEMS} more]`);
+    }
+    return kept;
+  }
+  const out: Record<string, unknown> = {};
+  const entries = Object.entries(value);
+  for (let index = 0; index < entries.length; index += 1) {
+    const [key, entry] = entries[index]!;
+    if (index >= LOG_MAX_KEYS) {
+      out[LOG_TRUNCATED_MARKER] = entries.length - LOG_MAX_KEYS;
+      break;
+    }
+    out[truncateLogString(key, LOG_MAX_STRING_CODE_UNITS)] = decycle(entry, budget, seen, depth + 1);
+  }
+  return out;
+}

package/src/observability/logger.ts

@@ -1,5 +1,6 @@
 import pino from 'pino';
 import { pushConsoleLog, type ConsoleLogLevel } from './log-ring';
+import { LOG_RING_MAX_CODE_UNITS, sanitizeLogValue, truncateLogString } from './log-sanitize';
 
 /**
  * Structured logger using Pino for production-ready logging.
@@ -58,19 +59,13 @@ const logger = pino({
  * without a cycle guard, so a circular log arg would overflow the stack
  * before redaction even runs. Errors collapse to name+message - stacks are
  * too long for a tail line and the message already carries the cause.
+ *
+ * Bounded in every dimension, not just depth: see the constants above. The
+ * node budget is carried by a mutable counter object rather than a return
+ * value, because a recursive walk that returned remaining budget would have to
+ * thread it through every branch and a missed one would silently unbound a
+ * subtree.
  */
-function decycle(value: unknown, seen: WeakSet<object> = new WeakSet(), depth = 0): unknown {
-  if (value === null || typeof value !== "object") return value;
-  if (seen.has(value)) return "[circular]";
-  if (depth > 5) return "[truncated]";
-  if (value instanceof Error) return { name: value.name, message: value.message };
-  seen.add(value);
-  if (Array.isArray(value)) return value.map((item) => decycle(item, seen, depth + 1));
-  const out: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value)) out[key] = decycle(entry, seen, depth + 1);
-  return out;
-}
-
 /**
  * Flatten a log call into one ring line. Args keep their real values: a log
  * line whose credential was rewritten into `***REDACTED***` is
@@ -79,7 +74,7 @@ function decycle(value: unknown, seen: WeakSet<object> = new WeakSet(), depth =
  */
 function safeLogValue(value: unknown): unknown {
   try {
-    return decycle(value);
+    return sanitizeLogValue(value);
   } catch {
     return "[unserializable args]";
   }
@@ -98,6 +93,10 @@ function formatRingMessage(msg: string, args: readonly unknown[]): string {
   } catch {
     rendered = "[unserializable args]";
   }
+  // Bounded on the way out too: the copy above caps each field, but a few
+  // hundred capped fields still render to a line long enough that the ring —
+  // a fixed 500-entry buffer — holds a meaningful fraction of one log call.
+  rendered = truncateLogString(rendered, LOG_RING_MAX_CODE_UNITS);
   return rendered.length > 0 ? `${msg} ${rendered}` : msg;
 }
 
@@ -160,6 +159,11 @@ function safeErrorForPino(error: Error): Error {
 }
 
 function logError(msg: string, error: Error | undefined, args: readonly unknown[]): void {
+  // Same fast-path as `logArgs`, and for the same reason: `safeErrorForPino`
+  // copies every own enumerable field of the error, and an error from a failed
+  // upstream call carries the response body. That copy is the largest one in
+  // this module and it used to run unconditionally.
+  if (!logger.isLevelEnabled("error")) return;
   const safe = safeLogArgs(args);
   const ringError = error === undefined ? undefined : safeErrorForRing(error);
   const pinoError = error === undefined ? undefined : safeErrorForPino(error);

package/src/observability/metrics.ts

@@ -279,10 +279,21 @@ export class PrometheusRegistry {
   readonly cartethyia_ip_abuse_keys: GaugeMetric;
   readonly cartethyia_quota_cache_entries: GaugeMetric;
   readonly cartethyia_model_catalog_entries: GaugeMetric;
+  readonly cartethyia_process_in_flight: GaugeMetric;
+  readonly cartethyia_process_concurrency_limit: GaugeMetric;
+  readonly cartethyia_telemetry_backlog_items: GaugeMetric;
+  readonly cartethyia_telemetry_backlog_bytes: GaugeMetric;
   readonly cartethyia_proxy_dial_proxy_resolved_total: CounterMetric;
   readonly proxy_provider_adapter_load_ms: HistogramMetric;
   readonly pool_cooldown_record_failed: CounterMetric;
   readonly quota_cache_invalidate_failed: CounterMetric;
+  /** Payload frames dropped because the writer backlog was at its bound. */
+  readonly cartethyia_payload_backlog_dropped_total: CounterMetric;
+  /**
+   * Telemetry backfill conflicts: same (tenant, request) identity with
+   * different content. Reported, never overwritten.
+   */
+  readonly cartethyia_telemetry_raw_conflicts_total: CounterMetric;
 
   private readonly all: RenderableMetric[] = [];
 
@@ -343,6 +354,22 @@ export class PrometheusRegistry {
       "cartethyia_memory_limit_bytes",
       "Container/cgroup memory limit in bytes (0 when unknown)",
     );
+    this.cartethyia_process_in_flight = this.gauge(
+      "cartethyia_process_in_flight",
+      "Gateway requests currently admitted into this process",
+    );
+    this.cartethyia_process_concurrency_limit = this.gauge(
+      "cartethyia_process_concurrency_limit",
+      "Effective in-flight ceiling for this process, derived from the memory limit",
+    );
+    this.cartethyia_telemetry_backlog_items = this.gauge(
+      "cartethyia_telemetry_backlog_items",
+      "Telemetry events queued for the next drain",
+    );
+    this.cartethyia_telemetry_backlog_bytes = this.gauge(
+      "cartethyia_telemetry_backlog_bytes",
+      "Estimated bytes queued for the next telemetry drain",
+    );
     this.cartethyia_routing_roundrobin_entries = this.gauge(
       "cartethyia_routing_roundrobin_entries",
       "Round-robin routing state entries by scope",
@@ -377,6 +404,14 @@ export class PrometheusRegistry {
       "quota_cache_invalidate_failed",
       "Quota cache invalidations that failed",
     );
+    this.cartethyia_payload_backlog_dropped_total = this.counter(
+      "cartethyia_payload_backlog_dropped_total",
+      "Payload captures dropped because the payload writer backlog was full",
+    );
+    this.cartethyia_telemetry_raw_conflicts_total = this.counter(
+      "cartethyia_telemetry_raw_conflicts_total",
+      "Telemetry backfill conflicts (same tenant/request identity, different content)",
+    );
   }
 
   counter(name: string, help: string, labelNames: readonly string[] = []): CounterMetric {

package/src/observability/payload-capture.ts

@@ -1,59 +1,93 @@
 import type { CartethyiaDatabase } from "../persistence/db-handle";
 import { DrizzleTelemetryStore } from "../persistence/stores/telemetry-store";
-import { prunePayloadFrames, writePayloadFrame } from "./payload-store";
+import { PayloadBacklogFullError, prunePayloadFrames, writePayloadFrame } from "./payload-store";
 import { resolveTelemetryPayloadMaxBytes } from "../config/telemetry";
+import { metrics } from "./metrics";
 import { preferencesReaderFor } from "../persistence/tenant-preferences";
 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.
  *
+ * An hour, not fifteen minutes: a frame is the only record of what a request
+ * actually sent and received, and the window is when an operator can still go
+ * back and read it. Fifteen minutes is shorter than the time between noticing
+ * a bad response and opening the drawer, so the frame was already gone by the
+ * time someone looked for it. The cost is disk, which the Data Management
+ * panel reports and a tenant can reclaim on demand.
+ *
  * 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;
+  const raw = Number(process.env.CARTETHYIA_TELEMETRY_PAYLOAD_RETENTION_MS ?? DEFAULT_PAYLOAD_RETENTION_MS);
+  if (!Number.isFinite(raw) || raw < 1_000 || raw > MAX_PAYLOAD_RETENTION_MS) return DEFAULT_PAYLOAD_RETENTION_MS;
   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 fallback window, exported so a test can assert the default without
+ * pinning the number.
  *
- * 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".
+ * A literal in a test is a veto on changing policy: the assertion fails the
+ * moment the default moves, so the number stops being a choice and becomes
+ * whatever the test happened to be written against.
  */
+export const DEFAULT_PAYLOAD_RETENTION_MS = 60 * 60_000;
+
+/** Upper bound for a deployment-level retention override, not a tenant setting. */
 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);
+/**
+ * Truncates a string to at most `maxBytes` UTF-8 bytes without splitting a
+ * code point.
+ *
+ * The budget contract everywhere in this module is **bytes**, not UTF-16 code
+ * units: `.length` on a CJK-heavy body counts one per character while the same
+ * text costs three bytes on the wire and on disk, so a "1 MiB" cap kept ~3 MiB
+ * of CJK content and dropped 3× more Latin content than the operator asked
+ * for. Slicing at a raw byte boundary can split a multi-byte sequence; this
+ * helper backs up to the last complete sequence so the truncated text stays
+ * valid.
+ */
+export function truncateUtf8(value: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  const totalBytes = Buffer.byteLength(value, "utf8");
+  if (totalBytes <= maxBytes) return value;
+  const sliced = Buffer.from(value, "utf8").subarray(0, maxBytes);
+  // Walk back from the cut (at most 3 bytes: the longest UTF-8 sequence is 4
+  // bytes) to the lead byte of the sequence the cut landed inside, then drop
+  // that whole sequence. A cut that lands between sequences stays put.
+  for (let back = 0; back < 4 && sliced.length - back > 0; back += 1) {
+    const byte = sliced[sliced.length - back - 1]!;
+    if ((byte & 0xc0) !== 0x80) {
+      // This is a lead byte (or ASCII): the sequence it starts has n bytes.
+      const sequenceLength =
+        byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+      // The cut is `back` bytes into this sequence. If the sequence does not
+      // fully fit within the slice, drop the whole sequence.
+      if (back + 1 < sequenceLength) {
+        return sliced.subarray(0, sliced.length - back - 1).toString("utf8");
+      }
+      return sliced.toString("utf8");
+    }
+    // Continuation byte: the lead byte is further back.
+  }
+  // Degenerate slice of only continuation bytes: nothing complete to keep.
+  return "";
 }
 
 /**
  * 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, and both live for the tenant's chosen
- * retention. Fail-closed on error.
+ * at the tenant's chosen depth. Their lifetime is the tenant's Request detail
+ * window, or the deployment default when unset. Fail-closed on error.
  */
 export async function resolvePayloadCapture(
   db: CartethyiaDatabase,
@@ -72,7 +106,11 @@ export async function resolvePayloadCapture(
     const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
     const mode = prefs?.telemetryPayloads;
     const depth = prefs?.telemetryPayloadDepth;
-    const retention = prefs?.telemetryPayloadRetentionMinutes;
+    const minutes = prefs?.telemetryWindowMinutes;
+    const retentionMs =
+      typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0
+        ? Math.min(MAX_PAYLOAD_RETENTION_MS, Math.floor(minutes * 60_000))
+        : payloadRetentionMs();
     return {
       ok: true,
       mode: mode === "full" || mode === "metadata" || mode === "none" ? mode : "none",
@@ -86,7 +124,7 @@ export async function resolvePayloadCapture(
               : depth === "full"
                 ? "maximum"
                 : "minimum",
-      retentionMs: retentionMsFor(retention as TelemetryPayloadRetentionMinutes | undefined),
+      retentionMs,
     };
   } catch {
     // A preference read that fails must not invent capture. Off keeps nothing.
@@ -135,7 +173,9 @@ export type PayloadCaptureState =
   /** The preference read failed, and capture fails closed. */
   | "skipped_preference_read_failed"
   /** The storage write failed after the decision to capture. */
-  | "failed_write";
+  | "failed_write"
+  /** The payload writer's backlog was at its bound, so the frame was dropped. */
+  | "failed_backlog";
 
 export interface PayloadCaptureInput {
   tenantId: string;
@@ -150,8 +190,7 @@ export interface PayloadCaptureInput {
    */
   maxBytes?: number;
   /**
-   * How long this frame lives, in ms. Defaults to the tenant's chosen
-   * retention, then the deployment default. Bounded by
+   * Retention for this capture; normally the deployment default. Bounded by
    * {@link MAX_PAYLOAD_RETENTION_MS} either way.
    */
   retentionMs?: number;
@@ -295,6 +334,8 @@ export function buildPayloadRecord(
   const kept: unknown[] = [];
   let accounted = 0;
   const truncatedKeys = new Set<keyof StoredPayload>();
+  // A fully-dropped body's own byte size, for the marker the drawer renders.
+  const truncatedOriginalBytes = new Map<keyof StoredPayload, number>();
   /**
    * Whether a surface kept a *body* — not whether it is merely non-null.
    *
@@ -311,13 +352,21 @@ export function buildPayloadRecord(
       continue;
     }
     const text = JSON.stringify(body);
-    if (accounted + text.length > maxBytes) {
+    // Accounted in UTF-8 bytes: the cap is a storage budget, and the bytes a
+    // body costs on disk are its UTF-8 size. Code-unit accounting under-counts
+    // multi-byte content ~3x (CJK) and over-allocates Latin content.
+    const textBytes = Buffer.byteLength(text, "utf8");
+    if (accounted + textBytes > maxBytes) {
+      // Same drop-then-marker rule as before — only the accounting basis is
+      // now bytes. A partial head would be raw JSON text where the drawer
+      // renders a structured panel, so the body is kept whole or marked.
       truncatedKeys.add(key);
+      truncatedOriginalBytes.set(key, textBytes);
       stored[key] = null;
       serialized.push("null");
       continue;
     }
-    accounted += text.length;
+    accounted += textBytes;
     stored[key] = body;
     serialized.push(text);
     kept.push(body);
@@ -332,7 +381,7 @@ export function buildPayloadRecord(
     _original_bytes: originalBytes,
     _hint: "Truncated by the capture cap — raise Settings → Telemetry payloads → Capture depth to keep more.",
   });
-  for (const key of truncatedKeys) stored[key] = marker(accounted);
+  for (const key of truncatedKeys) stored[key] = marker(truncatedOriginalBytes.get(key) ?? 0);
   return {
     request_id: input.requestId ?? null,
     captured_at: now,
@@ -385,7 +434,12 @@ export class TelemetryPayloadCapture {
     this.store = new DrizzleTelemetryStore(db);
   }
 
-  async capture(input: PayloadCaptureInput): Promise<{ id: string; expiresAt: Date }> {
+  async capture(input: PayloadCaptureInput): Promise<{
+    id: string;
+    expiresAt: Date;
+    /** Terminal capture state for the request row (`failed_backlog` on a dropped frame). */
+    payloadCaptureState?: PayloadCaptureState;
+  }> {
     if (!isCaptureAllowed(input)) {
       throw Object.assign(new Error("payload capture not opted in"), {
         code: "capture_not_opted_in",
@@ -402,14 +456,33 @@ export class TelemetryPayloadCapture {
       input.maxBytes ?? resolveTelemetryPayloadMaxBytes(),
       retentionMs,
     );
-    const reference = await writePayloadFrame(record, record.expires_at, record._serialized
-      ? {
-          requestId: record.request_id,
-          capturedAt: record.captured_at.toISOString(),
-          signals: record.signals,
-          bodies: record._serialized,
-        }
-      : undefined);
+    let reference;
+    try {
+      reference = await writePayloadFrame(record, record.expires_at, record._serialized
+        ? {
+            requestId: record.request_id,
+            capturedAt: record.captured_at.toISOString(),
+            signals: record.signals,
+            bodies: record._serialized,
+          }
+        : undefined);
+    } catch (error) {
+      if (error instanceof PayloadBacklogFullError) {
+        // The writer's backlog is at its bound: the frame is dropped here,
+        // counted, and surfaced on the request as its own terminal state —
+        // distinct from a storage failure, because "the disk is slow" and
+        // "capture burst past the backlog bound" need different fixes. No
+        // `telemetry_payloads` row is inserted: a row without a frame would
+        // read as a corrupt reference.
+        metrics.cartethyia_payload_backlog_dropped_total.inc(1);
+        return {
+          id: "",
+          expiresAt: record.expires_at,
+          payloadCaptureState: "failed_backlog",
+        };
+      }
+      throw error;
+    }
     // Typed columns only — bodies live in the frame file. The schema has no
     // jsonb body column, so a body cannot be written to Postgres here.
     return this.store.insertPayload({