cartethyia 2.5.10 → 2.6.0

package/src/transport/dispatch/attempt-finalize.ts

@@ -7,10 +7,9 @@ import type { UsageRecord } from "../../protocol/canonical-model";
 import { classifyUpstreamFailure } from "../failure-policy";
 import type { AdmissionLease } from "../../security/admission/contracts";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { TelemetryPayloadCapture } from "../../observability/payload-capture";
+import { resolvePayloadCapture, TelemetryPayloadCapture, truncateUtf8 } from "../../observability/payload-capture";
 import { payloadDirectory } from "../../observability/payload-store";
 import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
-import type { TelemetryPayloadDepth } from "../../console/settings/contracts";
 import type { ProxyRequestOutcome, ProxyRequestState } from "../request/state";
 import type { PayloadCaptureState } from "../../observability/payload-capture";
 import { finalizeRequestTelemetry } from "../guards/error-lifecycle";
@@ -22,126 +21,7 @@ import {
   recordPoolDispatchOutcome,
 } from "../../network/pool-health-machine";
 import { ProxyConnectRefusalError } from "../../network/pool/agent";
-import {
-  payloadCaptureKeepsBodies,
-  payloadRetentionMs,
-  resolvePayloadCapture,
-} from "../../observability/payload-capture";
-
-/**
- * True when the tenant keeps response bodies (mode `full`). The dispatch
- * path calls this once per attempt to decide whether the provider-response
- * tee is worth its clone + bounded read; `none`/`metadata` skip the body.
- */
-export async function shouldCaptureProviderBody(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-): Promise<boolean> {
-  return payloadCaptureKeepsBodies(db, tenantId);
-}
-
-/**
- * Per-stage cap for the provider request/response tee at one capture depth.
- *
- * The tee is what the drawer's "Provider Request" and "Provider Response"
- * panels read, so its cap is the most a provider panel can ever show. It used
- * to be a flat 256 KiB at every depth: on a large request the translated
- * provider body was clipped to 256 KiB before the shared record budget ever
- * ran, so a tenant who raised the depth to Maximum — 16 MiB — still saw a
- * quarter-megabyte provider request and an empty provider response. Derived
- * from the same depth tiers as the record budget, so raising the depth now
- * raises both.
- *
- * Capped at a quarter of the depth's total budget: four panels share it, and
- * one of them must never be able to spend the whole thing.
- */
-export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
-  if (depth === "moderate") return 2 * 1024 * 1024;
-  if (depth === "maximum") return 4 * 1024 * 1024;
-  return 256 * 1024;
-}
-
-/**
- * Same answer as {@link shouldCaptureProviderBody}, memoized on the request.
- *
- * The preference is a tenant setting, so it cannot change between attempts of
- * one request. Resolving it per attempt meant a request with several attempts
- * paid for it repeatedly, and the per-attempt answer could in principle differ
- * from the one the terminal capture then acted on. Passing `state` lets every
- * attempt of a request share one resolution.
- */
-export async function shouldCaptureProviderBodyForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<boolean> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly mode: string }
-    | { readonly ok: false };
-  return resolved.ok === true && resolved.mode === "full";
-}
-
-/**
- * The tenant's capture depth, memoized on the request like the mode above.
- *
- * Read *after* {@link shouldCaptureProviderBodyForRequest} has populated the
- * memo, so the two answers come from one preference read. It sizes the
- * provider tee: a tenant who raised the depth is asking for more of every
- * panel, and a flat cap would answer with the same clipped body regardless.
- */
-export async function resolveCaptureDepthForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<TelemetryPayloadDepth> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly depth: TelemetryPayloadDepth }
-    | { readonly ok: false };
-  return resolved.ok === true ? resolved.depth : "minimum";
-}
-
-/**
- * The tenant's chosen payload retention, memoized on the request like the mode
- * and depth above — and resolved *after* one of them has populated the memo, so
- * all three come from one preference read.
- *
- * Falls back to the deployment default when the read failed, which is the same
- * answer the capture path reaches on its own; returning it here keeps the
- * caller from having to know the fallback exists.
- */
-export async function resolveCaptureRetentionForRequest(
-  db: CartethyiaDatabase,
-  tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
-): Promise<number> {
-  if (state.payloadCapturePreference === undefined) {
-    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
-  }
-  const resolved = state.payloadCapturePreference as
-    | { readonly ok: true; readonly retentionMs: number }
-    | { readonly ok: false };
-  return resolved.ok === true ? resolved.retentionMs : payloadRetentionMs();
-}
-
-/**
- * Combined body cap for one capture depth. Fixed size tiers: every depth
- * stores all four drawer panels (client request, translated provider
- * request, raw provider response, final client response) — only the cap
- * changes, so raising the depth never changes *what* is visible, only how
- * much of large bodies survives. Moderate and maximum spike CPU/memory while
- * active; minimum is light enough to leave on.
- */
-function captureDepthMaxBytes(depth: TelemetryPayloadDepth): number {
-  if (depth === "moderate") return 8 * 1024 * 1024;
-  if (depth === "maximum") return 16 * 1024 * 1024;
-  return 1 * 1024 * 1024;
-}
+import { captureDepthMaxBytes, providerCaptureMaxBytes } from "./capture-policy";
 
 /**
  * What the client received for a failed terminal attempt, in the same public
@@ -186,21 +66,24 @@ async function readBoundedBody(response: Response, maxBytes: number): Promise<st
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   // Collect decoded chunks and join once: `+=` per chunk reallocates the
-  // prefix (O(n^2)). Truncation stays at the same decoded-char boundary.
+  // prefix (O(n^2)). The budget is UTF-8 **bytes** — the same basis the record
+  // budget and the request-line slice use — measured per decoded chunk, with
+  // the final chunk trimmed by truncateUtf8 so a code point is never split.
   const parts: string[] = [];
-  let total = 0;
+  let totalBytes = 0;
   try {
-    while (total < maxBytes) {
+    while (totalBytes < maxBytes) {
       const { done, value } = await reader.read();
       if (done) break;
       const chunk = decoder.decode(value, { stream: true });
-      if (total + chunk.length > maxBytes) {
-        parts.push(chunk.slice(0, maxBytes - total));
-        total = maxBytes;
+      const chunkBytes = Buffer.byteLength(chunk, "utf8");
+      if (totalBytes + chunkBytes > maxBytes) {
+        parts.push(truncateUtf8(chunk, maxBytes - totalBytes));
+        totalBytes = maxBytes;
         break;
       }
       parts.push(chunk);
-      total += chunk.length;
+      totalBytes += chunkBytes;
     }
   } catch {
     // Best-effort capture must never fail the request path.
@@ -339,11 +222,16 @@ export function captureProviderExchange(
       method: init?.method ?? "GET",
       url,
       ...(headers === undefined ? {} : { headers }),
-      // Capped the same way the response is. A capture is a diagnostic, and an
-      // unbounded translated request body per attempt — up to `maxAttempts` of
-      // them, all alive until the loop returns — costs more than it can tell
-      // an operator.
-      ...(rawBody === null ? {} : { body: parseCapturedBody(rawBody.slice(0, maxBytes)) }),
+      // `captureBody=false` is the `none`/`metadata` path: record that a body
+      // was sent and how big it was, without slicing or parsing it. The old
+      // shape sliced up to `maxBytes` of the translated body and ran it through
+      // `JSON.parse` for every attempt — content a metadata-mode tenant had
+      // explicitly declined to retain, paid on every dispatch.
+      ...(rawBody === null
+        ? {}
+        : captureBody
+          ? { body: parseCapturedBody(truncateUtf8(rawBody, maxBytes)) }
+          : { body_present: true, body_bytes: Buffer.byteLength(rawBody, "utf8") }),
     };
     const response = await inner(input, init);
     sink.response =
@@ -426,7 +314,7 @@ async function captureTerminalPayload(
         note("captured_metadata");
         return;
       }
-      await new TelemetryPayloadCapture(db).capture({
+      const metadataCapture = await new TelemetryPayloadCapture(db).capture({
         tenantId,
         requestId,
         requestBody: null,
@@ -436,13 +324,13 @@ async function captureTerminalPayload(
         scope: "tenant",
         tenantOptIn: true,
       });
-      note("captured_metadata");
+      note(metadataCapture.payloadCaptureState ?? "captured_metadata");
       return;
     }
     const maxBytes = captureDepthMaxBytes(depth);
     const providerRequest = providerCapture?.request ?? null;
     const providerResponse = await resolvedProviderResponse(providerCapture);
-    await new TelemetryPayloadCapture(db).capture({
+    const terminalCapture = await new TelemetryPayloadCapture(db).capture({
       tenantId,
       requestId,
       requestBody: requestBody ?? null,
@@ -455,7 +343,7 @@ async function captureTerminalPayload(
       scope: "tenant",
       tenantOptIn: true,
     });
-    note("captured");
+    note(terminalCapture.payloadCaptureState ?? "captured");
   } catch (error) {
     note("failed_write");
     reportCaptureFailure(error);

package/src/transport/dispatch/attempt-loop.ts

@@ -33,7 +33,13 @@ import type { NetworkPoolSelector } from "../../network/pool/selector";
 import type { ProxyRequestState } from "../request/state";
 import type { TelemetryBatchBuffer } from "../../observability/telemetry-buffer";
 import { flagPoolBlocked, flagPoolCooldown } from "../../network/pool-health";
-import { completeAttempt, errorClientResponseBody, estimatedUsage, type ProviderExchangeCapture } from "./attempt-finalize";
+import {
+  completeAttempt,
+  errorClientResponseBody,
+  estimatedUsage,
+  type AttemptCompletion,
+  type ProviderExchangeCapture,
+} from "./attempt-finalize";
 import { repriceUsage } from "../../providers/provider-usage";
 import { isFreeTierIpBlock, isOAuthCredentialInvalidated, shouldCooldownPool } from "./retry-policy";
 import { drainAbortReason } from "../shutdown-notice";
@@ -92,6 +98,50 @@ function buildMemberOrdinals(
   return ordinals;
 }
 
+/** Build the common failure payload; the call site supplies only attempt-specific decisions. */
+function failureCompletion(input: {
+  readonly state: ProxyRequestState;
+  readonly deps: AttemptLoopDeps;
+  readonly candidate?: RouteCandidate | undefined;
+  readonly status: AttemptCompletion["status"];
+  readonly errorCategory?: string;
+  readonly errorOrigin?: string;
+  readonly error: unknown;
+  readonly tenantId: string | null;
+  readonly terminal: boolean;
+  readonly networkPoolId?: string | undefined;
+  readonly lease?: AdmissionLease | undefined;
+  readonly commitUsage?: AttemptCompletion["commitUsage"];
+  readonly providerCapture?: ProviderExchangeCapture | undefined;
+  readonly includeClientResponse: boolean;
+}): AttemptCompletion {
+  const { state, deps, candidate } = input;
+  return {
+    status: input.status,
+    providerId: candidate?.provider_id ?? "",
+    ...(candidate?.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
+    ...(candidate?.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
+    ...(candidate?.model_id === undefined ? {} : { modelId: candidate.model_id }),
+    ...(input.networkPoolId === undefined ? {} : { networkPoolId: input.networkPoolId }),
+    ...(input.errorCategory === undefined ? {} : { errorCategory: input.errorCategory }),
+    ...(input.errorOrigin === undefined ? {} : { errorOrigin: input.errorOrigin }),
+    error: input.error,
+    ...(input.lease === undefined ? {} : { lease: input.lease }),
+    ...(input.commitUsage === undefined ? {} : { commitUsage: input.commitUsage }),
+    terminal: input.terminal,
+    tenantId: input.tenantId,
+    ingressBody: state.ingressBody,
+    responseBody: null,
+    ...(input.includeClientResponse && input.status !== "cancelled"
+      ? { clientResponseText: errorClientResponseBody(input.error) }
+      : {}),
+    ...(input.providerCapture === undefined ? {} : { providerCapture: input.providerCapture }),
+    db: deps.db,
+    ...(deps.telemetryBuffer === undefined ? {} : { telemetryBuffer: deps.telemetryBuffer }),
+    ...(deps.snapshotService === undefined ? {} : { snapshotService: deps.snapshotService }),
+  };
+}
+
 /** Route-specific preconditions resolved for one candidate before its leases are taken. */
 interface PreparedAttempt<TAdapter> {
   readonly credential: ResolvedCredential;
@@ -170,9 +220,14 @@ export async function runAttemptLoop<TResult, TAdapter>(
   // sink reaches the payload store. When the terminal attempt fails before it
   // fires an outbound request (lease/acquire/prepare threw, or failover
   // exhausted), its sink is empty and the drawer reads "—" for a request that
-  // DID reach an upstream on an earlier attempt. Keep the fired exchanges so
-  // the terminal completion can fall back to the last one that has a request.
-  const firedCaptures: ProviderExchangeCapture[] = [];
+  // DID reach an upstream on an earlier attempt. Only the LAST fired exchange
+  // is ever consulted — every consumer below falls back to the most recent
+  // capture that has a request — so this holds one reference, not the whole
+  // history: a request walking N attempts used to pin N provider exchanges
+  // (each holding its bounded provider tee) alive until the loop returned.
+  // Earlier attempts' captures are released as each new attempt fires; the
+  // payload store's own bounded writer is what bounds anything persisted.
+  let lastFiredCapture: ProviderExchangeCapture | undefined;
   const maxAttempts = resolveRouteMaxAttempts();
   // One combo member must not be able to spend the whole budget.
   //
@@ -222,36 +277,23 @@ export async function runAttemptLoop<TResult, TAdapter>(
       if (remainingMs < MIN_RETRY_BUDGET_MS) {
         if (lastError !== undefined && !state.completed) {
           const terminal = classifyTerminalOutcome(lastError, state.abortController.signal);
-          const lastFired = [...firedCaptures]
-            .reverse()
-            .find((capture) => capture.request !== null);
-          await completeAttempt(state, {
+          const lastFired =
+            lastFiredCapture?.request !== null && lastFiredCapture !== undefined
+              ? lastFiredCapture
+              : undefined;
+          await completeAttempt(state, failureCompletion({
+            state,
+            deps,
+            candidate,
             status: terminal.status,
-            providerId: candidate.provider_id,
-            ...(candidate.provider_account_id
-              ? { accountId: candidate.provider_account_id }
-              : {}),
-            ...(candidate.provider_account_label
-              ? { accountLabel: candidate.provider_account_label }
-              : {}),
             errorCategory: terminal.errorCategory,
             errorOrigin: terminal.errorOrigin,
-            modelId: candidate.model_id,
             error: lastError,
-            terminal: true,
             tenantId: input.tenantId,
-            ingressBody: state.ingressBody,
-            responseBody: null,
-            ...(terminal.status !== "cancelled"
-              ? { clientResponseText: errorClientResponseBody(lastError) }
-              : {}),
-            // Same fallback the terminal catch uses: a request that did fire
-            // upstream keeps that exchange in Request Detail.
-            ...(lastFired ? { providerCapture: lastFired } : {}),
-            db: deps.db,
-            ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
-            ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
-          });
+            terminal: true,
+            providerCapture: lastFired,
+            includeClientResponse: true,
+          }));
           metrics.proxy_requests_total.inc(1, {
             status: terminal.status === "cancelled" ? "cancelled" : "failed",
           });
@@ -358,7 +400,9 @@ export async function runAttemptLoop<TResult, TAdapter>(
         cancelled ||
         !isRetryableFailure(error) ||
         (index === candidates.length - 1 && !poolScopedFailure);
-      if (providerCapture.request !== null) firedCaptures.push(providerCapture);
+      // Track only the most recent fired exchange; the array this replaced
+      // accumulated every attempt's capture until the loop returned.
+      if (providerCapture.request !== null) lastFiredCapture = providerCapture;
       // The payload store only keeps the terminal attempt's exchange. When the
       // terminal attempt never fired (failover walked past the attempt that
       // did, or prepare/lease threw first), fall back to the last fired
@@ -367,50 +411,39 @@ export async function runAttemptLoop<TResult, TAdapter>(
       const terminalCapture =
         providerCapture.request !== null
           ? providerCapture
-          : [...firedCaptures].reverse().find((capture) => capture.request !== null) ??
-            providerCapture;
-      await completeAttempt(state, {
+          : lastFiredCapture ?? providerCapture;
+      await completeAttempt(state, failureCompletion({
+        state,
+        deps,
+        candidate,
         status: terminal.status,
-        providerId: candidate.provider_id,
-        ...(candidate.provider_account_id ? { accountId: candidate.provider_account_id } : {}),
-        ...(candidate.provider_account_label ? { accountLabel: candidate.provider_account_label } : {}),
         errorCategory: terminal.errorCategory,
         errorOrigin: terminal.errorOrigin,
-        modelId: candidate.model_id,
-        ...(networkPoolId ? { networkPoolId } : {}),
         error,
-        ...(lease ? { lease } : {}),
+        tenantId: input.tenantId,
+        terminal: terminalAttempt,
+        networkPoolId,
+        lease,
         // A failed attempt may have sent bytes upstream, so it is not free —
         // but it must not be charged the full input estimate plus a full
         // output reserve either, because a request that walks N candidates
         // would then leave N estimates on the counters for one client request.
         // Commit the input estimate only: nothing was generated, and the
         // `finally` release then refunds the (uncommitted) output reserve.
-        ...(!cancelled && bindingEstablished
-          ? {
-              commitUsage: repriceUsage(
-                estimatedUsage(leaseSource.estimatedInputTokens, 0),
-                candidate.provider_id,
-                candidate.model_id,
-              ),
-            }
-          : {}),
-        terminal: terminalAttempt,
-        tenantId: input.tenantId,
-        ingressBody: state.ingressBody,
-        responseBody: null,
+        commitUsage: !cancelled && bindingEstablished
+          ? repriceUsage(
+              estimatedUsage(leaseSource.estimatedInputTokens, 0),
+              candidate.provider_id,
+              candidate.model_id,
+            )
+          : undefined,
         // The client still receives the public error envelope on the wire —
         // store it so Request Detail's Client Response panel traces failures
         // exactly as the client saw them. Cancelled requests have no client
         // response (the caller is gone).
-        ...(terminalAttempt && !cancelled
-          ? { clientResponseText: errorClientResponseBody(error) }
-          : {}),
         providerCapture: terminalCapture,
-        db: deps.db,
-        ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
-        ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
-      });
+        includeClientResponse: terminalAttempt,
+      }));
       // A 403 can be a deterministic provider policy rejection, not an
       // invalid OAuth credential. Only the evidence-based classifier above
       // may trigger a refresh.
@@ -495,36 +528,25 @@ export async function runAttemptLoop<TResult, TAdapter>(
   if (!state.completed) {
     const terminal = classifyTerminalOutcome(lastError, state.abortController.signal);
     const lastCandidate = candidates[Math.min(index, candidates.length - 1)];
-    const terminalCapture = [...firedCaptures]
-      .reverse()
-      .find((capture) => capture.request !== null);
-    await completeAttempt(state, {
+    const terminalCapture =
+      lastFiredCapture?.request !== null && lastFiredCapture !== undefined
+        ? lastFiredCapture
+        : undefined;
+    await completeAttempt(state, failureCompletion({
+      state,
+      deps,
+      candidate: lastCandidate,
       status: terminal.status,
-      providerId: lastCandidate?.provider_id ?? "",
-      ...(lastCandidate?.provider_account_id
-        ? { accountId: lastCandidate.provider_account_id }
-        : {}),
-      ...(lastCandidate?.provider_account_label
-        ? { accountLabel: lastCandidate.provider_account_label }
-        : {}),
       errorCategory: terminal.errorCategory,
       errorOrigin: terminal.errorOrigin,
-      ...(lastCandidate?.model_id === undefined ? {} : { modelId: lastCandidate.model_id }),
       error: lastError,
       terminal: true,
       tenantId: input.tenantId,
-      ingressBody: state.ingressBody,
-      responseBody: null,
       // The client receives the public error envelope on the wire — store it
       // so the Client Response panel traces the failure as the client saw it.
-      ...(terminal.status === "cancelled"
-        ? {}
-        : { clientResponseText: errorClientResponseBody(lastError) }),
-      ...(terminalCapture === undefined ? {} : { providerCapture: terminalCapture }),
-      db: deps.db,
-      ...(deps.telemetryBuffer ? { telemetryBuffer: deps.telemetryBuffer } : {}),
-      ...(deps.snapshotService ? { snapshotService: deps.snapshotService } : {}),
-    });
+      providerCapture: terminalCapture,
+      includeClientResponse: true,
+    }));
   }
   metrics.proxy_requests_total.inc(1, { status: "failed" });
   throw lastError;

package/src/transport/dispatch/capture-policy.ts

@@ -0,0 +1,78 @@
+// Tenant payload-capture policy resolved once and shared by dispatch attempts.
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { payloadRetentionMs, resolvePayloadCapture } from "../../observability/payload-capture";
+import type { TelemetryPayloadDepth, TelemetryPayloadMode } from "../../console/settings/contracts";
+
+/** Per-stage body cap for the provider request/response tee. */
+export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
+  if (depth === "moderate") return 2 * 1024 * 1024;
+  if (depth === "maximum") return 4 * 1024 * 1024;
+  return 1024 * 1024;
+}
+
+/** Resolve whether provider bodies should be retained, memoized on this request. */
+export async function shouldCaptureProviderBodyForRequest(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: { payloadCapturePreference?: unknown },
+): Promise<boolean> {
+  if (state.payloadCapturePreference === undefined) {
+    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
+  }
+  const resolved = state.payloadCapturePreference as
+    | { readonly ok: true; readonly mode: string }
+    | { readonly ok: false };
+  return resolved.ok === true && resolved.mode === "full";
+}
+
+/** Resolve the tenant's capture mode once per request; failed reads fail closed. */
+export async function resolveCaptureModeForRequest(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: { payloadCapturePreference?: unknown },
+): Promise<TelemetryPayloadMode> {
+  if (state.payloadCapturePreference === undefined) {
+    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
+  }
+  const resolved = state.payloadCapturePreference as
+    | { readonly ok: true; readonly mode: TelemetryPayloadMode }
+    | { readonly ok: false };
+  return resolved.ok === true ? resolved.mode : "none";
+}
+
+/** Resolve the tenant's capture depth once per request. */
+export async function resolveCaptureDepthForRequest(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: { payloadCapturePreference?: unknown },
+): Promise<TelemetryPayloadDepth> {
+  if (state.payloadCapturePreference === undefined) {
+    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
+  }
+  const resolved = state.payloadCapturePreference as
+    | { readonly ok: true; readonly depth: TelemetryPayloadDepth }
+    | { readonly ok: false };
+  return resolved.ok === true ? resolved.depth : "minimum";
+}
+
+/** Resolve the tenant's payload retention once per request. */
+export async function resolveCaptureRetentionForRequest(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: { payloadCapturePreference?: unknown },
+): Promise<number> {
+  if (state.payloadCapturePreference === undefined) {
+    state.payloadCapturePreference = await resolvePayloadCapture(db, tenantId);
+  }
+  const resolved = state.payloadCapturePreference as
+    | { readonly ok: true; readonly retentionMs: number }
+    | { readonly ok: false };
+  return resolved.ok === true ? resolved.retentionMs : payloadRetentionMs();
+}
+
+/** Combined body cap for the four payload panels at one configured depth. */
+export function captureDepthMaxBytes(depth: TelemetryPayloadDepth): number {
+  if (depth === "moderate") return 8 * 1024 * 1024;
+  if (depth === "maximum") return 16 * 1024 * 1024;
+  return 1 * 1024 * 1024;
+}

package/src/transport/dispatch/proxy-request.ts

@@ -32,11 +32,13 @@ import {
   completionContext,
   estimatedUsage,
   parseCapturedBody,
+  terminalFailure,
+} from "./attempt-finalize";
+import {
   providerCaptureMaxBytes,
   resolveCaptureDepthForRequest,
   shouldCaptureProviderBodyForRequest,
-  terminalFailure,
-} from "./attempt-finalize";
+} from "./capture-policy";
 import { runAttemptLoop } from "./attempt-loop";
 import { projectForRoute, routeCapabilitiesFor } from "../translation/capabilities";
 import { dispatchStreamingAttempt } from "./streaming/stream";