cartethyia 2.7.3 → 2.7.5

package/src/security/ip-boundary.ts

@@ -3,185 +3,25 @@
 import { isIP } from "node:net";
 import type { TrustedProxyBoundary } from "../config/network";
 import { log } from "../observability/logger";
+import {
+  cidrContainsAddress,
+  ipv4ToNumber,
+  ipv6ToBigInt,
+  isLoopbackAddress,
+  unwrapMappedIpv4,
+} from "../network/ip-utils";
 
-function ipv4ToNumber(address: string): number | undefined {
-  const parts = address.split(".");
-  if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined;
-  const octets = parts.map(Number);
-  if (octets.some((part) => part < 0 || part > 255)) return undefined;
-  const [a, b, c, d] = octets;
-  if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
-  return ((a * 256 + b) * 256 + c) * 256 + d;
-}
-
-function ipv6ToBigInt(address: string): bigint | undefined {
-  const value = address.toLowerCase().split("%", 1)[0] ?? "";
-  if (value.includes(".")) return undefined;
-  const halves = value.split("::");
-  if (halves.length > 2) return undefined;
-  const left = halves[0] ? halves[0].split(":") : [];
-  const right = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
-  if (halves.length === 1 && left.length !== 8) return undefined;
-  const missing = 8 - left.length - right.length;
-  if (missing < 0 || (halves.length === 2 && missing < 1)) return undefined;
-  const groups = [...left, ...Array.from({ length: missing }, () => "0"), ...right];
-  if (groups.length !== 8 || groups.some((part) => !/^[0-9a-f]{1,4}$/.test(part)))
-    return undefined;
-  let result = 0n;
-  for (const group of groups) result = (result << 16n) | BigInt(Number.parseInt(group, 16));
-  return result;
-}
-
-/**
- * Unwraps an IPv4-mapped IPv6 address to plain IPv4.
- *
- * Bun reports an IPv4 loopback peer as `::ffff:127.0.0.1` on Windows, and
- * `isIP` classifies it as IPv6 — so `ipv6ToBigInt` (which bails on a dotted
- * quad) never matched `127.0.0.1/32`. The trust check therefore failed for the
- * exact peer `TRUSTED_PROXY_CIDRS=127.0.0.1/32` is meant to cover, forwarded
- * headers were ignored, and every cloudflared request stored the loopback peer
- * as the client address. Accepts both the dotted and the hex (`::ffff:7f00:1`)
- * spelling.
- */
-function unwrapMappedIpv4(address: string): string {
-  const value = address.toLowerCase().split("%", 1)[0] ?? "";
-  // Recognize the mapped range STRUCTURALLY, not by its compressed spelling. The
-  // old `startsWith("::ffff:")` test missed any form that writes the leading zero
-  // groups out — `0:0:0:0:0:ffff:7f00:1` is the same host as `::ffff:127.0.0.1`,
-  // but it failed the prefix test, fell through to `ipv6ToBigInt`, and was treated
-  // as an unrelated IPv6 address. The trust check then refused a peer the allowlist
-  // covered, and `canonicalClientIpKey` minted a second key for one host — which is
-  // stored on issued child keys for consistent usage reporting and audit.
-  //
-  // A mapped address is `::ffff:<32 bits>`, i.e. the first 80 bits are zero and the
-  // next 16 are `0xffff`. Matching that is the same test `isIP` uses internally.
-  const tail = mappedIpv4Tail(value);
-  if (tail === undefined) return address;
-  // `mappedIpv4Tail` always returns two hex groups, so the dotted and hex
-  // spellings have already converged by here.
-  const groups = tail.split(":");
-  if (groups.length !== 2) return address;
-  const high = Number.parseInt(groups[0] ?? "", 16);
-  const low = Number.parseInt(groups[1] ?? "", 16);
-  if (!Number.isInteger(high) || !Number.isInteger(low) || high < 0 || high > 0xffff || low < 0 || low > 0xffff)
-    return address;
-  return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
-}
-
-/**
- * The 32-bit tail of an IPv4-mapped IPv6 address, or `undefined` when `value` is
- * not one. Accepts every spelling of the same address: `::ffff:1.2.3.4`,
- * `::ffff:102:304`, `0:0:0:0:0:ffff:102:304`, and `::ffff:0:102:304`.
- *
- * Works by normalizing to exactly eight 16-bit groups first. That is the only way
- * to compare spellings: a dotted tail is written as ONE colon-separated token but
- * occupies TWO group slots, so any check that counts `split(":")` entries gets the
- * position of the `ffff` marker wrong.
- */
-function mappedIpv4Tail(value: string): string | undefined {
-  const groups = normalizeIpv6Groups(value);
-  if (groups === undefined) return undefined;
-  // The first five groups (80 bits) must be zero, and the sixth must be `ffff`.
-  for (let index = 0; index < 5; index += 1) {
-    if (groups[index] !== "0") return undefined;
-  }
-  if (groups[5] !== "ffff") return undefined;
-  const high = groups[6];
-  const low = groups[7];
-  if (high === undefined || low === undefined) return undefined;
-  return `${high}:${low}`;
-}
-
-/**
- * An IPv6 literal as exactly eight lowercase 16-bit hex groups, or `undefined`
- * when it is not one. Expands a `::` run and converts a trailing dotted quad into
- * the two groups it represents.
- */
-function normalizeIpv6Groups(value: string): string[] | undefined {
-  const text = value.trim();
-  if (text.length === 0) return undefined;
-  const doubleIndex = text.indexOf("::");
-  // More than one `::` is invalid, as is a `::` inside a group.
-  if (doubleIndex !== text.lastIndexOf("::")) return undefined;
-
-  const headText = doubleIndex >= 0 ? text.slice(0, doubleIndex) : text;
-  const tailText = doubleIndex >= 0 ? text.slice(doubleIndex + 2) : "";
-  const head = headText.length > 0 ? headText.split(":") : [];
-  const tail = tailText.length > 0 ? tailText.split(":") : [];
-
-  // A dotted quad is a single token that fills two groups.
-  const expandDotted = (tokens: string[]): string[] | undefined => {
-    const last = tokens[tokens.length - 1];
-    if (last === undefined || !last.includes(".")) return tokens;
-    const quad = last.split(".");
-    if (quad.length !== 4) return undefined;
-    const octets = quad.map((part) => Number(part));
-    if (octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined;
-    const [a, b, c, d] = octets;
-    if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
-    const high = ((a << 8) | b).toString(16);
-    const low = ((c << 8) | d).toString(16);
-    return [...tokens.slice(0, -1), high, low];
-  };
-
-  const expandedHead = expandDotted(head);
-  const expandedTail = expandDotted(tail);
-  if (expandedHead === undefined || expandedTail === undefined) return undefined;
-
-  let full: string[];
-  if (doubleIndex >= 0) {
-    const missing = 8 - expandedHead.length - expandedTail.length;
-    // `::` must stand for at least one group, so exactly-8 without it is invalid.
-    if (missing < 1) return undefined;
-    full = [...expandedHead, ...Array.from({ length: missing }, () => "0"), ...expandedTail];
-  } else {
-    full = expandedHead;
-  }
-  if (full.length !== 8) return undefined;
-  const normalized: string[] = [];
-  for (const group of full) {
-    if (!/^[0-9a-f]{1,4}$/.test(group)) return undefined;
-    normalized.push(Number.parseInt(group, 16).toString(16));
-  }
-  return normalized;
-}
+export { isLoopbackAddress };
 
 function matchesCidr(address: string, cidr: string): boolean {
-  const [network, rawPrefix] = cidr.split("/");
-  if (!network) return false;
-  // A bare address (`"127.0.0.1"`) has no prefix and means "this exact host". A
-  // present-but-blank prefix (`"10.0.0.0/"`) must NOT be treated as /0: `Number("")`
-  // is 0, and /0 matches every address — which made `isTrustedProxyPeer` true for
-  // ANY peer, so the gateway believed a caller's own `X-Forwarded-For` and every
-  // per-address decision downstream (abuse throttling, model bans, the audit
-  // trail) read a forged value.
-  //
-  // Requiring a run of digits also refuses the exotic spellings `Number` accepts
-  // for zero (`-0`, `+0`, `0x0`, `0b0`, `0o0`, `0.0`), all of which are typos
-  // rather than a deliberate "trust everyone".
-  const prefixText = rawPrefix === undefined ? undefined : rawPrefix.trim();
-  if (prefixText !== undefined && !/^\d+$/.test(prefixText)) return false;
-  // A mapped peer and a plain-IPv4 allowlist entry describe the same host.
-  const subject = unwrapMappedIpv4(address);
-  const base = unwrapMappedIpv4(network);
-  const family = isIP(subject);
-  if (family === 4) {
-    const value = ipv4ToNumber(subject);
-    const networkValue = ipv4ToNumber(base);
-    if (value === undefined || networkValue === undefined) return false;
-    const prefix = prefixText === undefined ? 32 : Number(prefixText);
-    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false;
-    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
-    return ((value >>> 0) & mask) === ((networkValue >>> 0) & mask);
-  }
-  if (family !== 6) return false;
-  const value = ipv6ToBigInt(subject);
-  const networkValue = ipv6ToBigInt(base);
-  if (value === undefined || networkValue === undefined) return false;
-  const prefix = prefixText === undefined ? 128 : Number(prefixText);
-  if (!Number.isInteger(prefix) || prefix < 0 || prefix > 128) return false;
-  const shift = BigInt(128 - prefix);
-  return (value >> shift) === (networkValue >> shift);
+  // `unwrapMapped: true`: a mapped peer and a plain-IPv4 allowlist entry
+  // describe the same host (Bun reports the IPv4 loopback peer as
+  // `::ffff:127.0.0.1` on Windows). `requirePrefix: false`: a bare address
+  // (`"127.0.0.1"`) means "this exact host".
+  return cidrContainsAddress(address, cidr, {
+    requirePrefix: false,
+    unwrapMapped: true,
+  });
 }
 
 function isTrustedPeer(peer: string, boundary: TrustedProxyBoundary): boolean {
@@ -206,20 +46,7 @@ const CLIENT_IDENTITY_HEADERS = [
 
 /**
  * True when `address` is a loopback address.
- *
- * Structural, not a string-prefix test: `127.0.0.1`, `::1`, and the mapped
- * `::ffff:127.0.0.1` a Windows/Bun peer arrives as are all the same host, and
- * a prefix test would miss the mapped form — the exact shape that hid this
- * class of bug before.
  */
-export function isLoopbackAddress(address: string): boolean {
-  const normalized = unwrapMappedIpv4(address.trim().split("%", 1)[0] ?? "");
-  if (normalized === "::1") return true;
-  if (isIP(normalized) !== 4) return false;
-  const value = ipv4ToNumber(normalized);
-  // 127.0.0.0/8 — the whole loopback block, not just 127.0.0.1.
-  return value !== undefined && ((value >>> 0) & 0xff000000) === (127 << 24);
-}
 
 /**
  * Whether a peer may vouch for forwarded headers *for client-address

package/src/security/model-access-rule.ts

@@ -24,7 +24,7 @@ import type { ApiKeyModelAccessMode } from "../persistence/schema";
 export type ModelRejectionReason = "model-denied" | "model-not-allowed";
 
 /** The subset of an authorization snapshot this rule reads. */
-export interface ModelAccessPolicy {
+interface ModelAccessPolicy {
   readonly model_access_mode?: ApiKeyModelAccessMode | null | undefined;
   readonly model_list?: readonly string[] | ReadonlySet<string> | null | undefined;
 }

package/src/security/outbound-headers.ts

@@ -21,6 +21,24 @@ export const X_FRAME_OPTIONS = "DENY";
  */
 export const BADGE_IMAGE_ORIGIN = "https://img.shields.io";
 
+/**
+ * Invariant: upstream response headers are NEVER forwarded wholesale to
+ * callers. There is no denylist-and-forward step on the egress path — the
+ * success projection (`proxySuccessHeaders` in
+ * `transport/dispatch/upstream.ts`) rebuilds the caller-facing header set from
+ * scratch (`cache-control: no-store`, `x-request-id`, and
+ * `GATEWAY_SECURITY_HEADERS` below), so credential-bearing upstream fields
+ * (`set-cookie`, `www-authenticate`, `proxy-authorization`) and hop-by-hop
+ * headers can never leak through by omission from a strip list.
+ *
+ * Any future feature that wants to pass upstream response fields to a caller
+ * must copy only the specific content-bearing headers it needs — do not
+ * reintroduce a "forward everything except" filter. A module implementing
+ * exactly that (`src/network/response-headers.ts` + `stripResponseHeaders`)
+ * existed once and was deleted as dead code (see git history for it), because
+ * every egress path had already moved to the rebuild-from-scratch projection.
+ */
+
 /**
  * Security headers on every `/v1` response, whichever path produced it.
  *

package/src/shared/coerce.ts

@@ -13,6 +13,25 @@ export function asRecord(value: unknown): Record<string, unknown> | undefined {
     : undefined;
 }
 
+/**
+ * Narrow a stored `auth_state`/JSONB value to a plain object. Postgres'
+ * drizzle `jsonb` arrives as a POJO; SQLite's text-backed column arrives as
+ * a JSON STRING. Parse the string form so both backends hand downstream
+ * readers the same shape — otherwise auth-state-dependent providers (Qoder's
+ * userId/machineId, Trae's region, …) silently lose their identity on the
+ * SQLite backend.
+ */
+export function asJsonbRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "string") {
+    try {
+      return asRecord(JSON.parse(value));
+    } catch {
+      return undefined;
+    }
+  }
+  return asRecord(value);
+}
+
 /** Narrow to a finite number, else `undefined`. `NaN`/`Infinity` are not numbers here. */
 export function asNumber(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;

package/src/shared/invoke-guard.ts

@@ -0,0 +1,47 @@
+/**
+ * InvokeGuard — a process-local foreground-activity gauge (G-03).
+ *
+ * Every foreground request path signals its activity here: the console control
+ * plane bumps the counter for the duration of each request, and the proxy data
+ * plane exposes its in-flight count through `setProxyBusySource`. The scheduled
+ * worker registry (and the sweep runner between waves) consults
+ * `foregroundBusy()` before starting background work, so a page open / an
+ * invoke in progress is never forced to share the single event loop with a
+ * heavy sweep.
+ *
+ * The defer policy is at the call sites (scheduler: bounded pause before a
+ * tick; sweep runner: bounded pause between waves). This module only owns the
+ * gauge — it never decides when to pause.
+ */
+
+/** Console request counter. Bumped per in-flight console request. */
+let consoleActivity = 0;
+
+/** Optional live source of "the proxy plane is busy" (the in-flight store). */
+let proxyBusySource: (() => boolean) | undefined;
+
+/** Registers the proxy plane's busy source (wired once from the app root). */
+export function setProxyBusySource(source: () => boolean): void {
+  proxyBusySource = source;
+}
+
+/** Marks a foreground console request; returns the matching end callback. */
+export function beginConsoleActivity(): () => void {
+  consoleActivity += 1;
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+    consoleActivity = Math.max(0, consoleActivity - 1);
+  };
+}
+
+/** Live foreground-request count (console counter + proxy source if wired). */
+export function foregroundActivityCount(): number {
+  return consoleActivity + (proxyBusySource?.() === true ? 1 : 0);
+}
+
+/** True when any foreground work is in flight right now. */
+export function foregroundBusy(): boolean {
+  return consoleActivity > 0 || (proxyBusySource?.() ?? false);
+}

package/src/transport/contracts.ts

@@ -54,12 +54,12 @@ export interface CanonicalAdapter {
  */
 
 /** One native service: the path it is served at and the kind its models carry. */
-export interface NativeServiceRoute {
+interface NativeServiceRoute {
   readonly serviceKind: Exclude<ServiceKind, "llm">;
   readonly path: string;
 }
 
-export const NATIVE_SERVICES: readonly NativeServiceRoute[] = [
+const NATIVE_SERVICES: readonly NativeServiceRoute[] = [
   { serviceKind: "systemone", path: "/v1/systemone" },
   { serviceKind: "websearch", path: "/v1/search" },
   { serviceKind: "imageGeneration", path: "/v1/images/generations" },
@@ -75,7 +75,7 @@ export const NATIVE_SERVICE_PATHS: readonly string[] = NATIVE_SERVICES.map(
 );
 
 /** Whether `path` is served by a native service route. */
-export function isNativeServicePath(path: string | undefined): boolean {
+function isNativeServicePath(path: string | undefined): boolean {
   return path !== undefined && NATIVE_SERVICE_PATHS.includes(path);
 }
 
@@ -97,6 +97,15 @@ export function isNativeServicePath(path: string | undefined): boolean {
  */
 export const TOKEN_COUNT_PATH = "/v1/messages/count_tokens";
 
+/**
+ * The native Codex compaction route (`POST /v1/responses/compact`).
+ *
+ * Not a native service (it has no `serviceKind` of its own — Codex rows are
+ * `llm`-adjacent), so it is declared separately from `NATIVE_SERVICE_PATHS`,
+ * but its body is equally opaque and must skip the canonical chat stage.
+ */
+export const RESPONSES_COMPACT_PATH = "/v1/responses/compact";
+
 /**
  * Whether `path` reads a JSON body that is *not* a canonical chat request.
  *
@@ -105,7 +114,7 @@ export const TOKEN_COUNT_PATH = "/v1/messages/count_tokens";
  * will either reject a body the upstream accepts or plan it twice.
  */
 export function isOpaqueBodyRoute(path: string | undefined): boolean {
-  return isNativeServicePath(path) || path === TOKEN_COUNT_PATH;
+  return isNativeServicePath(path) || path === TOKEN_COUNT_PATH || path === RESPONSES_COMPACT_PATH;
 }
 
 /** The route path serving `serviceKind`, when one is declared. */

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

@@ -394,7 +394,7 @@ let captureFailureReported = false;
  * deployment condition that does not change per request, so repeating it for
  * every request would bury the rest of the log without adding information.
  */
-export function reportCaptureFailure(error: unknown): void {
+function reportCaptureFailure(error: unknown): void {
   if (captureFailureReported) return;
   captureFailureReported = true;
   const directory = payloadDirectory();
@@ -425,7 +425,7 @@ export function terminalFailure(
     return new GatewayError(
       "transport_unavailable",
       502,
-      "The upstream closed the response without reporting a result. Retry; if it keeps happening, the account or pool is unstable.",
+      "The upstream closed the response without reporting a result (request {requestId}). Retry; if it keeps happening, the account or pool is unstable. The connection ghosted us — come back in a moment 👻",
       {},
       "upstream",
     );
@@ -437,7 +437,7 @@ export function terminalFailure(
     const details: Record<string, unknown> = {};
     if (terminal.provider_stop_reason) details["provider_code"] = terminal.provider_stop_reason;
     if (terminal.stop_details) Object.assign(details, terminal.stop_details);
-    const message = typeof details["message"] === "string" ? details["message"] : "upstream request failed";
+    const message = typeof details["message"] === "string" ? details["message"] : "upstream request failed (request {requestId}). The upstream came back empty-handed — retry 🌙";
    // Preserve the upstream's error code when the provider embedded it in
    // `stop_details` (Cursor writes `quota_exceeded` and `authentication_failed`
    // there). Wrapping every terminal failure as `transport_unavailable` discarded
@@ -460,7 +460,7 @@ export function terminalFailure(
     // reports it as truncation instead.
     return options.truncated === true
       ? undefined
-      : new GatewayError("transport_closed", 499, "request was cancelled");
+      : new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
   }
   return undefined;
 }
@@ -823,6 +823,7 @@ export async function completeAttempt(
           (completion.error instanceof ProxyConnectRefusalError ? "network" : undefined);
         await recordPoolDispatchOutcome(completion.db, completion.networkPoolId, {
           succeeded: completion.status === "completed",
+          ...(completion.providerId === undefined ? {} : { providerId: completion.providerId }),
           ...(completion.error === undefined ? {} : { error: completion.error }),
           // A CONNECT refusal is the proxy's own answer, given before any
           // upstream was dialed, so it is a network fault even though the

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

@@ -41,7 +41,8 @@ import {
   type ProviderExchangeCapture,
 } from "./attempt-finalize";
 import { repriceUsage } from "../../providers/provider-usage";
-import { isFreeTierIpBlock, isOAuthCredentialInvalidated, shouldCooldownPool } from "./retry-policy";
+import { classifyEgressFailure } from "../../network/rate-limit-verdict";
+import { isOAuthCredentialInvalidated } from "./retry-policy";
 import { drainAbortReason } from "../shutdown-notice";
 
 /**
@@ -316,7 +317,7 @@ export async function runAttemptLoop<TResult, TAdapter>(
     };
     try {
       if (state.abortController.signal.aborted)
-        throw new GatewayError("transport_closed", 499, "request was cancelled");
+        throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
       const { credential, adapter } = await input.prepare(candidate);
       const host = input.resolveHost?.(candidate);
       // Single attempt-lease manager owns acquisition order (admission →
@@ -353,9 +354,10 @@ export async function runAttemptLoop<TResult, TAdapter>(
       });
     } catch (error) {
       // A drain aborts the controller, so a mid-flight attempt unwinds here as
-      // an abort. Surface the typed shutdown error (503 shutting_down /
-      // restart_for_update) instead of an opaque `transport_closed`, so the
-      // client's JSON error — not just the SSE path — names the real cause.
+      // an abort. Surface the typed shutdown error (503 shutting_down, reason
+      // restart_for_update for an update drain) instead of an opaque
+      // `transport_closed`, so the client's JSON error — not just the SSE path —
+      // names the real cause.
       const drain = drainAbortReason(state.abortController.signal.reason);
       if (drain !== undefined) error = drain;
       lastError = error;
@@ -374,11 +376,12 @@ export async function runAttemptLoop<TResult, TAdapter>(
       // single candidate carrying every pool). Judging it there is what made a
       // refused egress end the request instead of failing over to a healthy
       // one.
-      const rateLimitedPool = !cancelled && shouldCooldownPool(error, candidate.provider_id);
+      const egressVerdict = !cancelled ? classifyEgressFailure(error, candidate.provider_id) : { kind: "none" } as const;
       // A free-tier refusal is only ever this provider's: the guard is gated on
       // `ipScopedRateLimit` in the provider metadata, so a 403 from any other
       // upstream still means what it always did and never retires an egress.
-      const blockedPool = !cancelled && isFreeTierIpBlock(error, candidate.provider_id);
+      const rateLimitedPool = egressVerdict.kind === "cooldown";
+      const blockedPool = egressVerdict.kind === "blocked";
       const poolScopedFailure =
         (rateLimitedPool || blockedPool) &&
         networkPoolId !== undefined &&

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

@@ -1,8 +1,35 @@
 // 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 { resolvePayloadCapture } from "../../observability/payload-capture";
 import type { TelemetryPayloadDepth, TelemetryPayloadMode } from "../../console/settings/contracts";
 
+/** The resolved payload-capture preference, memoized on the request state. */
+export type PayloadCapturePreference =
+  | {
+      readonly ok: true;
+      readonly mode: TelemetryPayloadMode;
+      readonly depth: TelemetryPayloadDepth;
+      readonly retentionMs: number;
+    }
+  | { readonly ok: false };
+
+/** The slice of request state that memoizes the capture preference. */
+export type CapturePreferenceState = { payloadCapturePreference?: PayloadCapturePreference };
+
+/** Resolves the tenant's capture preference once, memoized on the request state. */
+async function resolveCapturePreference(
+  db: CartethyiaDatabase,
+  tenantId: string | null,
+  state: CapturePreferenceState,
+): Promise<PayloadCapturePreference> {
+  let preference = state.payloadCapturePreference;
+  if (preference === undefined) {
+    preference = await resolvePayloadCapture(db, tenantId);
+    state.payloadCapturePreference = preference;
+  }
+  return preference;
+}
+
 /** Per-stage body cap for the provider request/response tee. */
 export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
   if (depth === "moderate") return 2 * 1024 * 1024;
@@ -14,14 +41,9 @@ export function providerCaptureMaxBytes(depth?: TelemetryPayloadDepth): number {
 export async function shouldCaptureProviderBodyForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): 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 };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   return resolved.ok === true && resolved.mode === "full";
 }
 
@@ -29,14 +51,9 @@ export async function shouldCaptureProviderBodyForRequest(
 export async function resolveCaptureModeForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): 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 };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   return resolved.ok === true ? resolved.mode : "none";
 }
 
@@ -44,32 +61,12 @@ export async function resolveCaptureModeForRequest(
 export async function resolveCaptureDepthForRequest(
   db: CartethyiaDatabase,
   tenantId: string | null,
-  state: { payloadCapturePreference?: unknown },
+  state: CapturePreferenceState,
 ): 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 };
+  const resolved = await resolveCapturePreference(db, tenantId, state);
   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;