@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/runtime/debug-context-model.ts

@@ -0,0 +1,1319 @@
+/**
+ * The debug context file (`context-<stamp>.json`): what a ticket carries for whoever fixes the bug, a person or
+ * a coding agent. DOM-free, so the web toolbar, native clients, the service's second redaction pass and the
+ * console all use the same shape, the same limits and the same brief.
+ *
+ * Every section is optional: a host turns each signal on or off in code (`DebugContextOptions`), and a reader
+ * says "not captured" rather than "nothing happened".
+ */
+import {
+  newTally,
+  type JsonBag,
+  scrubId,
+  scrubText,
+  scrubUrl,
+  scrubValue,
+  type RedactionTally,
+} from "./debug-context-redact.js";
+
+export const DEBUG_CONTEXT_PREFIX = "context-";
+/** The most a context file may weigh once serialized. Larger files are trimmed (`fitDebugContext`). */
+export const DEBUG_CONTEXT_MAX_BYTES = 64 * 1024;
+/** Rough characters-per-token for the brief's budget. */
+const BRIEF_MAX_CHARS = 24_000;
+
+/** On whenever a host turns debug context on. */
+export const DEFAULT_SIGNALS = [
+  "errors",
+  "network",
+  "responseExcerpts",
+  "steps",
+  "environment",
+  "page",
+  "build",
+  "target",
+  "host",
+  "resources",
+  "lifecycle",
+] as const;
+
+/** Off unless a host names them. */
+export const OPT_IN_SIGNALS = [
+  "staleBuild",
+  "componentStacks",
+  "domExcerpt",
+  "queries",
+  "realtime",
+  "stores",
+  "storeValues",
+  "consoleLog",
+  "performance",
+  "storage",
+  "bodies",
+] as const;
+
+export type DebugSignal = (typeof DEFAULT_SIGNALS)[number] | (typeof OPT_IN_SIGNALS)[number];
+export const DEBUG_SIGNALS: readonly DebugSignal[] = [...DEFAULT_SIGNALS, ...OPT_IN_SIGNALS];
+
+/**
+ * Who files the report. `reviewer`: people testing the app with the comment toolbar. `support`: the app's own
+ * customers through a help form, so failed-response excerpts start off.
+ */
+export type DebugAudience = "reviewer" | "support";
+
+export type FlagValue = string | number | boolean | null;
+
+/** The host app's build. `deployed` is the build the server serves now, for spotting a stale tab. */
+export type HostBuild = {
+  commit?: string;
+  version?: string;
+  env?: string;
+  builtAt?: string;
+  deployed?: string;
+};
+
+export type RealtimeState = {
+  status?: string;
+  /** Epoch ms of the last message received. */
+  lastMessageAt?: number;
+  reconnects?: number;
+  lastClose?: { code?: number; reason?: string };
+};
+
+/** What the host knows and the browser does not. Ids, never emails or names of people. */
+export type HostContext = {
+  user?: { id?: string; role?: string; plan?: string; locale?: string };
+  org?: { id?: string; name?: string };
+  flags?: Record<string, FlagValue>;
+  build?: HostBuild;
+  /** The id the host's backend logs carry for this page or request chain (`traceparent`'s trace id). */
+  traceId?: string;
+  sessionId?: string;
+  /** The router's pattern for the page, e.g. `/projects/:id`. */
+  routePattern?: string;
+  realtime?: RealtimeState;
+  /** A few more facts of the host's own, at most 20. */
+  extra?: Record<string, FlagValue>;
+};
+
+/** One query of a data-fetching cache (TanStack Query, SWR): its state, never its data. */
+export type QuerySummary = {
+  key: unknown;
+  status?: string;
+  fetchStatus?: string;
+  error?: unknown;
+  /** Epoch ms the data last changed. */
+  updatedAt?: number;
+  observers?: number;
+};
+
+/** How a host turns debug context on and what it allows. All of it is code, in the host app. */
+export type DebugContextOptions = {
+  /** Default true once an options object is given. */
+  enabled?: boolean;
+  /** Default `reviewer` in the toolbar. */
+  audience?: DebugAudience;
+  /** Turns single signals on or off; anything not named keeps its default (`DEFAULT_SIGNALS`). */
+  signals?: Partial<Record<DebugSignal, boolean>>;
+  /** Static build facts. `getContext().build` wins field by field. */
+  build?: HostBuild;
+  /** Asked once per report, with a 300 ms limit. */
+  getContext?: () => HostContext | Promise<HostContext>;
+  /** The last word before the file leaves the browser: change it, or return null to send none. */
+  beforeCapture?: (file: DebugContextFile) => DebugContextFile | null;
+  /** Told the report's id, so the host can log it beside its own trace. */
+  onReport?: (reportId: string) => void;
+  /** Read for the `queries` signal. */
+  queries?: () => readonly QuerySummary[];
+  /** Read for the `stores` signal, by name. */
+  stores?: Record<string, () => unknown>;
+  /** More response headers that carry request ids. */
+  idHeaders?: readonly string[];
+  /** Requests whose full bodies are kept (the `bodies` signal): URL prefixes or patterns. */
+  bodyUrls?: readonly (string | RegExp)[];
+  /** `localStorage`/`sessionStorage` keys whose values are kept (the `storage` signal). Others: names only. */
+  storageValueKeys?: readonly string[];
+  /** A request slower than this is kept as slow. Default 3000. */
+  slowMs?: number;
+};
+
+/** `true`, `false`, or the options. Off when absent. */
+export type DebugContextConfig = boolean | DebugContextOptions;
+
+export type ResolvedDebugContext = {
+  audience: DebugAudience;
+  signals: Record<DebugSignal, boolean>;
+  options: DebugContextOptions;
+  slowMs: number;
+};
+
+/** The host's config as one shape, or null when debug context is off. */
+export function resolveDebugContext(
+  config: DebugContextConfig | null | undefined,
+  fallbackAudience: DebugAudience = "reviewer",
+): ResolvedDebugContext | null {
+  // A script-tag host's value arrives unchecked: anything but `true` or a plain object is off.
+  if (config !== true && (typeof config !== "object" || config === null || Array.isArray(config)))
+    return null;
+  const options: DebugContextOptions = config === true ? {} : config;
+  if (options.enabled === false) return null;
+  const audience: DebugAudience =
+    options.audience === "support" || options.audience === "reviewer"
+      ? options.audience
+      : fallbackAudience;
+  const signals = {} as Record<DebugSignal, boolean>;
+  for (const signal of DEFAULT_SIGNALS) signals[signal] = true;
+  for (const signal of OPT_IN_SIGNALS) signals[signal] = false;
+  // Decision of 2026-11-12: excerpts on for reviewers, off for the support pill, switchable.
+  if (audience === "support") signals.responseExcerpts = false;
+  for (const signal of DEBUG_SIGNALS) {
+    const given = options.signals?.[signal];
+    if (typeof given === "boolean") signals[signal] = given;
+  }
+  if (!signals.stores) signals.storeValues = false;
+  const slowMs =
+    typeof options.slowMs === "number" && options.slowMs >= 100 && options.slowMs <= 120_000
+      ? options.slowMs
+      : 3000;
+  return { audience, signals, options, slowMs };
+}
+
+/**
+ * What, of a host's config, decides what is captured: a capture restarts only when this changes. Functions
+ * are left out; they are read live (`liveDebugOptions`).
+ */
+export function debugContextKey(config: DebugContextConfig | null | undefined): string {
+  const resolved = resolveDebugContext(config ?? false);
+  if (!resolved) return "off";
+  const { options } = resolved;
+  return JSON.stringify([
+    resolved.audience,
+    resolved.signals,
+    resolved.slowMs,
+    options.idHeaders ?? [],
+    (options.bodyUrls ?? []).map(String),
+    options.storageValueKeys ?? [],
+    Object.keys(options.stores ?? {}),
+    options.build ?? null,
+  ]);
+}
+
+/**
+ * The options as they are now, with every function reading `read()` when it is called: a host that passes a
+ * new options object on every render keeps one running capture that still calls its latest functions.
+ */
+export function liveDebugOptions(
+  read: () => DebugContextConfig | null | undefined,
+): DebugContextOptions {
+  const now = () => {
+    const value = read();
+    return value && typeof value === "object" ? value : undefined;
+  };
+  const first = now() ?? {};
+  return {
+    ...first,
+    ...(first.getContext ? { getContext: () => now()?.getContext?.() ?? {} } : {}),
+    ...(first.beforeCapture
+      ? {
+          beforeCapture: (file: DebugContextFile) => {
+            const current = now()?.beforeCapture;
+            return current ? current(file) : file;
+          },
+        }
+      : {}),
+    ...(first.onReport ? { onReport: (id: string) => now()?.onReport?.(id) } : {}),
+    ...(first.queries ? { queries: () => now()?.queries?.() ?? [] } : {}),
+    ...(first.stores
+      ? {
+          stores: Object.fromEntries(
+            Object.keys(first.stores).map((name) => [name, () => now()?.stores?.[name]?.()]),
+          ),
+        }
+      : {}),
+  };
+}
+
+// ---------------------------------------------------------------- the file
+
+export type DebugErrorKind =
+  | "uncaught"
+  | "rejection"
+  | "console"
+  | "boundary"
+  | "resource"
+  | "csp"
+  | "reported";
+
+export type DebugError = {
+  /** Milliseconds before the report (negative). */
+  t: number;
+  kind: DebugErrorKind;
+  level: "error" | "warn";
+  message: string;
+  stack?: string[];
+  /** `file:line:col` where the browser said it happened. */
+  source?: string;
+  componentStack?: string[];
+  count: number;
+};
+
+export type DebugRequest = {
+  t: number;
+  method: string;
+  url: string;
+  /** 0 when there was no answer. */
+  status: number;
+  ms?: number;
+  bytes?: number;
+  contentType?: string;
+  excerpt?: string;
+  graphql?: { operation?: string; errors: string[] };
+  ids?: Record<string, string>;
+  requestBody?: string;
+  responseBody?: string;
+};
+
+export type DebugStep =
+  | { t: number; type: "navigate"; path: string }
+  | { t: number; type: "click"; label: string }
+  | { t: number; type: "input"; label: string; redacted: boolean; value?: string }
+  | { t: number; type: "console"; level: "error" | "warn"; message: string }
+  | { t: number; type: "network"; method: string; path: string; status: number }
+  | { t: number; type: "say"; text: string };
+
+export type LifecycleEvent =
+  | "online"
+  | "offline"
+  | "hidden"
+  | "visible"
+  | "foreground"
+  | "background";
+
+export type DebugContextFile = {
+  v: 1;
+  kind: "debug-context";
+  capturedAt: string;
+  audience: DebugAudience;
+  platform: "web" | "ios" | "android";
+  page?: {
+    url: string;
+    route: string;
+    routePattern?: string;
+    title?: string;
+    referrer?: string;
+    loadedAgoMs?: number;
+    softNavigations?: number;
+    visibility?: string;
+  };
+  build?: { host?: HostBuild; toolbar?: string; staleHost?: boolean };
+  client?: {
+    browser?: string;
+    os?: string;
+    device?: string;
+    viewport?: [number, number];
+    dpr?: number;
+    zoom?: number;
+    locale?: string;
+    timezone?: string;
+    colorScheme?: string;
+    reducedMotion?: boolean;
+    online?: boolean;
+    connection?: string;
+    touch?: boolean;
+    appVersion?: string;
+    appBuild?: string;
+    appVariant?: string;
+  };
+  identity?: {
+    userId?: string;
+    role?: string;
+    plan?: string;
+    locale?: string;
+    orgId?: string;
+    orgName?: string;
+  };
+  flags?: Record<string, FlagValue>;
+  extra?: Record<string, FlagValue>;
+  target?: {
+    component?: string;
+    file?: string;
+    stack?: string[];
+    role?: string;
+    name?: string;
+    tag?: string;
+    html?: string;
+    box?: [number, number, number, number];
+    styles?: Record<string, string>;
+  };
+  errors?: DebugError[];
+  logs?: { t: number; level: string; message: string }[];
+  network?: {
+    failed: DebugRequest[];
+    slow: DebugRequest[];
+    pending: DebugRequest[];
+    aborted: number;
+  };
+  steps?: DebugStep[];
+  lifecycle?: { t: number; event: LifecycleEvent }[];
+  performance?: {
+    longTasks?: number;
+    longestTaskMs?: number;
+    inpMs?: number;
+    lcpMs?: number;
+    cls?: number;
+    loadMs?: number;
+    heapMb?: number;
+  };
+  queries?: {
+    key: string;
+    status?: string;
+    fetchStatus?: string;
+    error?: string;
+    updatedAgoMs?: number;
+    observers?: number;
+  }[];
+  stores?: JsonBag;
+  storage?: {
+    local?: { key: string; bytes: number; value?: string }[];
+    session?: { key: string; bytes: number; value?: string }[];
+    cookies?: string[];
+    indexedDb?: string[];
+  };
+  realtime?: {
+    status?: string;
+    lastMessageAgoMs?: number;
+    reconnects?: number;
+    lastClose?: { code?: number; reason?: string };
+  };
+  join: { reportId: string; traceId?: string; sessionId?: string; requestIds?: string[] };
+  /** Which signals were on, so a reader can tell "off" from "nothing happened". */
+  signals: DebugSignal[];
+  redaction: { rules: 1; masked: number; dropped: number; truncated: boolean };
+};
+
+export function isDebugContextName(name: string) {
+  return /^context-[A-Za-z0-9._-]{1,80}\.json$/.test(name);
+}
+
+/** `context-<stamp>.json` for a report taken at `at`. */
+export function debugContextName(at = new Date()) {
+  return `${DEBUG_CONTEXT_PREFIX}${at.toISOString().slice(0, 19).replace(/[:T]/g, "-")}.json`;
+}
+
+/** A report id: sortable by time, unguessable, safe in a header or a log line. */
+export function newReportId(now = Date.now()) {
+  const random = new Uint8Array(8);
+  // React Native without a crypto polyfill has no getRandomValues; the id only needs to be hard to guess.
+  const source = (
+    globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => Uint8Array } }
+  ).crypto;
+  if (typeof source?.getRandomValues === "function") source.getRandomValues(random);
+  else
+    for (let index = 0; index < random.length; index += 1)
+      random[index] = Math.floor(Math.random() * 256);
+  return `ctx_${now.toString(36)}${[...random].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
+// ---------------------------------------------------------------- reading an untrusted file
+
+type Bag = { readonly [key: string]: unknown };
+
+function bag(value: unknown): Bag | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Bag) : null;
+}
+
+function str(value: unknown, max: number, tally: RedactionTally): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = scrubText(value, max, tally).trim();
+  return text || undefined;
+}
+
+function num(value: unknown, min = -1e12, max = 1e12): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max
+    ? Math.round(value * 1000) / 1000
+    : undefined;
+}
+
+function bool(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function list<T>(value: unknown, max: number, read: (item: unknown) => T | undefined): T[] {
+  if (!Array.isArray(value)) return [];
+  const out: T[] = [];
+  for (const item of value) {
+    if (out.length >= max) break;
+    const read1 = read(item);
+    if (read1 !== undefined) out.push(read1);
+  }
+  return out;
+}
+
+/** `T` with no property holding `undefined`: what `compact` returns. */
+type Defined<T> = { [K in keyof T]?: Exclude<T[K], undefined> };
+
+/** The object without its `undefined` properties, or undefined when none is left. */
+function compact<T extends object>(value: T): Defined<T> | undefined {
+  const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+  return entries.length ? (Object.fromEntries(entries) as Defined<T>) : undefined;
+}
+
+/** A copy without `key`. */
+function without<T extends object, K extends keyof T>(value: T, key: K): Omit<T, K> {
+  const { [key]: _dropped, ...rest } = value;
+  return rest;
+}
+
+const SAFE_ID = /^[A-Za-z0-9_.:-]{1,120}$/;
+
+function flagRecord(
+  value: unknown,
+  max: number,
+  tally: RedactionTally,
+): Record<string, FlagValue> | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  const out: Record<string, FlagValue> = {};
+  let count = 0;
+  for (const [key, item] of Object.entries(input)) {
+    if (count >= max) break;
+    const name = scrubText(key, 80, tally);
+    if (!name) continue;
+    if (typeof item === "string") out[name] = scrubText(item, 120, tally);
+    else if (typeof item === "number" && Number.isFinite(item)) out[name] = item;
+    else if (typeof item === "boolean" || item === null) out[name] = item;
+    else continue;
+    count += 1;
+  }
+  return count ? out : undefined;
+}
+
+function hostBuild(value: unknown, tally: RedactionTally): HostBuild | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  return compact({
+    commit: str(input["commit"], 64, tally),
+    version: str(input["version"], 64, tally),
+    env: str(input["env"], 40, tally),
+    builtAt: str(input["builtAt"], 40, tally),
+    deployed: str(input["deployed"], 64, tally),
+  });
+}
+
+const ERROR_KINDS: readonly DebugErrorKind[] = [
+  "uncaught",
+  "rejection",
+  "console",
+  "boundary",
+  "resource",
+  "csp",
+  "reported",
+];
+
+function readError(value: unknown, tally: RedactionTally): DebugError | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  const message = str(input["message"], 500, tally);
+  const kind = ERROR_KINDS.find((item) => item === input["kind"]);
+  if (!message || !kind) return undefined;
+  const stack = list(input["stack"], 12, (line) => str(line, 240, tally));
+  const componentStack = list(input["componentStack"], 12, (line) => str(line, 120, tally));
+  return {
+    t: num(input["t"]) ?? 0,
+    kind,
+    level: input["level"] === "warn" ? "warn" : "error",
+    message,
+    ...(stack.length ? { stack } : {}),
+    ...(str(input["source"], 240, tally) ? { source: str(input["source"], 240, tally)! } : {}),
+    ...(componentStack.length ? { componentStack } : {}),
+    count: Math.max(1, Math.min(10_000, Math.round(num(input["count"]) ?? 1))),
+  };
+}
+
+function readIds(value: unknown): Record<string, string> | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  const out: Record<string, string> = {};
+  let count = 0;
+  for (const [name, item] of Object.entries(input)) {
+    if (count >= 10) break;
+    if (!/^[a-z0-9-]{1,64}$/.test(name) || typeof item !== "string") continue;
+    const id = scrubId(item);
+    if (!id) continue;
+    out[name] = id;
+    count += 1;
+  }
+  return count ? out : undefined;
+}
+
+function readRequest(value: unknown, tally: RedactionTally): DebugRequest | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  const url = typeof input["url"] === "string" ? scrubUrl(input["url"], 400, undefined, tally) : "";
+  if (!url) return undefined;
+  const method =
+    typeof input["method"] === "string"
+      ? input["method"]
+          .toUpperCase()
+          .replace(/[^A-Z]/g, "")
+          .slice(0, 10)
+      : "";
+  const graphqlIn = bag(input["graphql"]);
+  const graphqlErrors = graphqlIn
+    ? list(graphqlIn["errors"], 5, (item) => str(item, 300, tally))
+    : [];
+  const operation = graphqlIn ? str(graphqlIn["operation"], 80, tally) : undefined;
+  return {
+    t: num(input["t"]) ?? 0,
+    method: method || "GET",
+    url,
+    status: Math.round(num(input["status"], 0, 999) ?? 0),
+    ...(num(input["ms"], 0, 3_600_000) !== undefined
+      ? { ms: Math.round(num(input["ms"], 0, 3_600_000)!) }
+      : {}),
+    ...(num(input["bytes"], 0, 1e10) !== undefined
+      ? { bytes: Math.round(num(input["bytes"], 0, 1e10)!) }
+      : {}),
+    ...(str(input["contentType"], 80, tally)
+      ? { contentType: str(input["contentType"], 80, tally)! }
+      : {}),
+    ...(str(input["excerpt"], 2048, tally) ? { excerpt: str(input["excerpt"], 2048, tally)! } : {}),
+    ...(graphqlIn && (graphqlErrors.length || operation)
+      ? { graphql: { ...(operation ? { operation } : {}), errors: graphqlErrors } }
+      : {}),
+    ...(readIds(input["ids"]) ? { ids: readIds(input["ids"])! } : {}),
+    ...(str(input["requestBody"], 16_384, tally)
+      ? { requestBody: str(input["requestBody"], 16_384, tally)! }
+      : {}),
+    ...(str(input["responseBody"], 16_384, tally)
+      ? { responseBody: str(input["responseBody"], 16_384, tally)! }
+      : {}),
+  };
+}
+
+function readStep(value: unknown, tally: RedactionTally): DebugStep | undefined {
+  const input = bag(value);
+  if (!input) return undefined;
+  const t = num(input["t"]) ?? 0;
+  switch (input["type"]) {
+    case "navigate": {
+      const path =
+        typeof input["path"] === "string"
+          ? scrubUrl(input["path"], 300, "https://app.invalid", tally)
+          : "";
+      return path ? { t, type: "navigate", path } : undefined;
+    }
+    case "click": {
+      const label = str(input["label"], 120, tally);
+      return label ? { t, type: "click", label } : undefined;
+    }
+    case "input": {
+      const label = str(input["label"], 120, tally);
+      if (!label) return undefined;
+      const entered = input["redacted"] === true ? undefined : str(input["value"], 80, tally);
+      return {
+        t,
+        type: "input",
+        label,
+        redacted: !entered,
+        ...(entered ? { value: entered } : {}),
+      };
+    }
+    case "console": {
+      const message = str(input["message"], 300, tally);
+      return message
+        ? { t, type: "console", level: input["level"] === "warn" ? "warn" : "error", message }
+        : undefined;
+    }
+    case "network": {
+      const path =
+        typeof input["path"] === "string"
+          ? scrubUrl(input["path"], 300, "https://app.invalid", tally)
+          : "";
+      if (!path) return undefined;
+      const method =
+        typeof input["method"] === "string"
+          ? input["method"]
+              .toUpperCase()
+              .replace(/[^A-Z]/g, "")
+              .slice(0, 10)
+          : "GET";
+      return {
+        t,
+        type: "network",
+        method: method || "GET",
+        path,
+        status: Math.round(num(input["status"], 0, 999) ?? 0),
+      };
+    }
+    case "say": {
+      const text = str(input["text"], 400, tally);
+      return text ? { t, type: "say", text } : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+const LIFECYCLE: readonly LifecycleEvent[] = [
+  "online",
+  "offline",
+  "hidden",
+  "visible",
+  "foreground",
+  "background",
+];
+
+function storageList(value: unknown, tally: RedactionTally) {
+  const out = list(value, 100, (item) => {
+    const input = bag(item);
+    const key = input ? str(input["key"], 120, tally) : undefined;
+    if (!input || !key) return undefined;
+    const entry: { key: string; bytes: number; value?: string } = {
+      key,
+      bytes: Math.round(num(input["bytes"], 0, 1e9) ?? 0),
+    };
+    const kept = str(input["value"], 500, tally);
+    if (kept) entry.value = kept;
+    return entry;
+  });
+  return out.length ? out : undefined;
+}
+
+/**
+ * A context file rebuilt from untrusted JSON: only known fields, every string redacted again, every list and
+ * string bounded. Null when it is not a context file. Running it on its own output changes nothing but the
+ * counts, so the browser, the service and the console can all run it.
+ */
+export function sanitizeDebugContext(value: unknown): DebugContextFile | null {
+  const input = bag(value);
+  if (!input || input["v"] !== 1 || input["kind"] !== "debug-context") return null;
+  const tally = newTally();
+  const before = bag(input["redaction"]);
+  const joinIn = bag(input["join"]);
+  const reportId =
+    typeof joinIn?.["reportId"] === "string" && SAFE_ID.test(joinIn["reportId"])
+      ? joinIn["reportId"]
+      : null;
+  if (!reportId) return null;
+  const capturedAt =
+    typeof input["capturedAt"] === "string" && !Number.isNaN(Date.parse(input["capturedAt"]))
+      ? new Date(Date.parse(input["capturedAt"])).toISOString()
+      : null;
+  if (!capturedAt) return null;
+  const file: DebugContextFile = {
+    v: 1,
+    kind: "debug-context",
+    capturedAt,
+    audience: input["audience"] === "support" ? "support" : "reviewer",
+    platform:
+      input["platform"] === "ios" || input["platform"] === "android" ? input["platform"] : "web",
+    join: { reportId },
+    signals: list(input["signals"], DEBUG_SIGNALS.length, (item) =>
+      DEBUG_SIGNALS.find((signal) => signal === item),
+    ),
+    redaction: { rules: 1, masked: 0, dropped: 0, truncated: before?.["truncated"] === true },
+  };
+
+  const page = bag(input["page"]);
+  if (page) {
+    const url =
+      typeof page["url"] === "string" ? scrubUrl(page["url"], 1000, undefined, tally) : "";
+    const route =
+      typeof page["route"] === "string"
+        ? scrubUrl(page["route"], 300, "https://app.invalid", tally)
+        : "";
+    if (url || route) {
+      file.page = {
+        url,
+        route,
+        ...compact({
+          routePattern: str(page["routePattern"], 200, tally),
+          title: str(page["title"], 160, tally),
+          referrer:
+            typeof page["referrer"] === "string" && page["referrer"]
+              ? scrubUrl(page["referrer"], 300, undefined, tally)
+              : undefined,
+          loadedAgoMs: num(page["loadedAgoMs"], 0, 1e11),
+          softNavigations: num(page["softNavigations"], 0, 1e6),
+          visibility: str(page["visibility"], 20, tally),
+        }),
+      };
+    }
+  }
+
+  const build = bag(input["build"]);
+  if (build) {
+    const kept = compact({
+      host: hostBuild(build["host"], tally),
+      toolbar: str(build["toolbar"], 80, tally),
+      staleHost: bool(build["staleHost"]),
+    });
+    if (kept) file.build = kept;
+  }
+
+  const client = bag(input["client"]);
+  if (client) {
+    const viewport =
+      Array.isArray(client["viewport"]) &&
+      client["viewport"].length === 2 &&
+      num(client["viewport"][0], 0, 100_000) !== undefined &&
+      num(client["viewport"][1], 0, 100_000) !== undefined
+        ? ([
+            Math.round(client["viewport"][0] as number),
+            Math.round(client["viewport"][1] as number),
+          ] as [number, number])
+        : undefined;
+    const kept = compact({
+      browser: str(client["browser"], 80, tally),
+      os: str(client["os"], 80, tally),
+      device: str(client["device"], 80, tally),
+      viewport,
+      dpr: num(client["dpr"], 0, 16),
+      zoom: num(client["zoom"], 0, 16),
+      locale: str(client["locale"], 40, tally),
+      timezone: str(client["timezone"], 60, tally),
+      colorScheme: str(client["colorScheme"], 20, tally),
+      reducedMotion: bool(client["reducedMotion"]),
+      online: bool(client["online"]),
+      connection: str(client["connection"], 20, tally),
+      touch: bool(client["touch"]),
+      appVersion: str(client["appVersion"], 40, tally),
+      appBuild: str(client["appBuild"], 40, tally),
+      appVariant: str(client["appVariant"], 40, tally),
+    });
+    if (kept) file.client = kept;
+  }
+
+  const identity = bag(input["identity"]);
+  if (identity) {
+    const kept = compact({
+      userId: str(identity["userId"], 120, tally),
+      role: str(identity["role"], 60, tally),
+      plan: str(identity["plan"], 60, tally),
+      locale: str(identity["locale"], 40, tally),
+      orgId: str(identity["orgId"], 120, tally),
+      orgName: str(identity["orgName"], 120, tally),
+    });
+    if (kept) file.identity = kept;
+  }
+
+  const flags = flagRecord(input["flags"], 100, tally);
+  if (flags) file.flags = flags;
+  const extra = flagRecord(input["extra"], 20, tally);
+  if (extra) file.extra = extra;
+
+  const target = bag(input["target"]);
+  if (target) {
+    const box =
+      Array.isArray(target["box"]) &&
+      target["box"].length === 4 &&
+      target["box"].every((item) => num(item, -1e6, 1e6) !== undefined)
+        ? (target["box"].map((item) => Math.round(item as number)) as [
+            number,
+            number,
+            number,
+            number,
+          ])
+        : undefined;
+    const stylesIn = bag(target["styles"]);
+    const styles: Record<string, string> = {};
+    if (stylesIn) {
+      for (const [name, item] of Object.entries(stylesIn).slice(0, 20)) {
+        if (/^[a-z-]{1,40}$/.test(name) && typeof item === "string")
+          styles[name] = scrubText(item, 80, tally);
+      }
+    }
+    const stack = list(target["stack"], 30, (item) => str(item, 80, tally));
+    const kept = compact({
+      component: str(target["component"], 120, tally),
+      file: str(target["file"], 240, tally),
+      stack: stack.length ? stack : undefined,
+      role: str(target["role"], 40, tally),
+      name: str(target["name"], 160, tally),
+      tag: str(target["tag"], 20, tally),
+      html: str(target["html"], 4096, tally),
+      box,
+      styles: Object.keys(styles).length ? styles : undefined,
+    });
+    if (kept) file.target = kept;
+  }
+
+  const errors = list(input["errors"], 30, (item) => readError(item, tally));
+  if (errors.length) file.errors = errors;
+  const logs = list(input["logs"], 50, (item) => {
+    const entry = bag(item);
+    const message = entry ? str(entry["message"], 300, tally) : undefined;
+    return entry && message
+      ? { t: num(entry["t"]) ?? 0, level: str(entry["level"], 10, tally) ?? "log", message }
+      : undefined;
+  });
+  if (logs.length) file.logs = logs;
+
+  const network = bag(input["network"]);
+  if (network) {
+    file.network = {
+      failed: list(network["failed"], 30, (item) => readRequest(item, tally)),
+      slow: list(network["slow"], 20, (item) => readRequest(item, tally)),
+      pending: list(network["pending"], 20, (item) => readRequest(item, tally)),
+      aborted: Math.round(num(network["aborted"], 0, 1e6) ?? 0),
+    };
+  }
+
+  const steps = list(input["steps"], 150, (item) => readStep(item, tally));
+  if (steps.length) file.steps = steps;
+  const lifecycle = list(input["lifecycle"], 30, (item) => {
+    const entry = bag(item);
+    const event = entry ? LIFECYCLE.find((name) => name === entry["event"]) : undefined;
+    return entry && event ? { t: num(entry["t"]) ?? 0, event } : undefined;
+  });
+  if (lifecycle.length) file.lifecycle = lifecycle;
+
+  const performance = bag(input["performance"]);
+  if (performance) {
+    const kept = compact({
+      longTasks: num(performance["longTasks"], 0, 1e6),
+      longestTaskMs: num(performance["longestTaskMs"], 0, 1e7),
+      inpMs: num(performance["inpMs"], 0, 1e7),
+      lcpMs: num(performance["lcpMs"], 0, 1e7),
+      cls: num(performance["cls"], 0, 100),
+      loadMs: num(performance["loadMs"], 0, 1e7),
+      heapMb: num(performance["heapMb"], 0, 1e6),
+    });
+    if (kept) file.performance = kept;
+  }
+
+  const queries = list(input["queries"], 50, (item) => {
+    const entry = bag(item);
+    const key = entry ? str(entry["key"], 200, tally) : undefined;
+    if (!entry || !key) return undefined;
+    return {
+      key,
+      ...compact({
+        status: str(entry["status"], 20, tally),
+        fetchStatus: str(entry["fetchStatus"], 20, tally),
+        error: str(entry["error"], 300, tally),
+        updatedAgoMs: num(entry["updatedAgoMs"], 0, 1e11),
+        observers: num(entry["observers"], 0, 1e6),
+      }),
+    };
+  });
+  if (queries.length) file.queries = queries;
+
+  const stores = bag(input["stores"]);
+  if (stores) {
+    const out: JsonBag = {};
+    for (const [name, item] of Object.entries(stores).slice(0, 10)) {
+      out[scrubText(name, 60, tally)] = scrubValue(item, {
+        depth: 6,
+        text: 300,
+        entries: 50,
+        tally,
+      });
+    }
+    if (Object.keys(out).length) file.stores = out;
+  }
+
+  const storage = bag(input["storage"]);
+  if (storage) {
+    const cookies = list(storage["cookies"], 50, (item) => str(item, 80, tally));
+    const indexedDb = list(storage["indexedDb"], 30, (item) => str(item, 80, tally));
+    const kept = compact({
+      local: storageList(storage["local"], tally),
+      session: storageList(storage["session"], tally),
+      cookies: cookies.length ? cookies : undefined,
+      indexedDb: indexedDb.length ? indexedDb : undefined,
+    });
+    if (kept) file.storage = kept;
+  }
+
+  const realtime = bag(input["realtime"]);
+  if (realtime) {
+    const close = bag(realtime["lastClose"]);
+    const kept = compact({
+      status: str(realtime["status"], 40, tally),
+      lastMessageAgoMs: num(realtime["lastMessageAgoMs"], 0, 1e11),
+      reconnects: num(realtime["reconnects"], 0, 1e6),
+      lastClose: close
+        ? compact({ code: num(close["code"], 0, 9999), reason: str(close["reason"], 120, tally) })
+        : undefined,
+    });
+    if (kept) file.realtime = kept;
+  }
+
+  if (joinIn) {
+    const traceId =
+      typeof joinIn["traceId"] === "string" ? scrubId(joinIn["traceId"]).slice(0, 120) : "";
+    const sessionId =
+      typeof joinIn["sessionId"] === "string" ? scrubId(joinIn["sessionId"]).slice(0, 120) : "";
+    const requestIds = list(joinIn["requestIds"], 30, (item) =>
+      typeof item === "string" ? scrubId(item) || undefined : undefined,
+    );
+    if (traceId) file.join.traceId = traceId;
+    if (sessionId) file.join.sessionId = sessionId;
+    if (requestIds.length) file.join.requestIds = requestIds;
+  }
+
+  // Counts from the browser's pass, plus anything this pass found.
+  file.redaction.masked = Math.round(num(before?.["masked"], 0, 1e9) ?? 0) + tally.masked;
+  file.redaction.dropped = Math.round(num(before?.["dropped"], 0, 1e9) ?? 0) + tally.dropped;
+  return file;
+}
+
+/** UTF-8 length of `text`, without an encoder (React Native has none). */
+function utf8Length(text: string) {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      bytes += 4;
+      index += 1;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+export function debugContextBytes(file: DebugContextFile) {
+  return utf8Length(JSON.stringify(file));
+}
+
+/**
+ * The file cut down to `maxBytes`, dropping the least useful parts first: store state, storage, the cache,
+ * logs, bodies, then the oldest steps, excerpts and stacks. Marks `redaction.truncated` when anything went.
+ */
+export function fitDebugContext(
+  file: DebugContextFile,
+  maxBytes = DEBUG_CONTEXT_MAX_BYTES,
+): DebugContextFile {
+  let current: DebugContextFile = file;
+  if (debugContextBytes(current) <= maxBytes) return current;
+  const stripBodies = (request: DebugRequest): DebugRequest =>
+    without(without(request, "requestBody"), "responseBody");
+  const cuts: Array<(next: DebugContextFile) => DebugContextFile> = [
+    (next) => without(next, "stores"),
+    (next) => without(next, "storage"),
+    (next) => (next.queries ? { ...next, queries: next.queries.slice(0, 10) } : next),
+    (next) => without(next, "logs"),
+    (next) =>
+      next.network
+        ? {
+            ...next,
+            network: {
+              ...next.network,
+              failed: next.network.failed.map(stripBodies),
+              slow: next.network.slow.map(stripBodies),
+            },
+          }
+        : next,
+    (next) => (next.target ? { ...next, target: without(next.target, "html") } : next),
+    (next) => (next.steps ? { ...next, steps: next.steps.slice(-50) } : next),
+    (next) =>
+      next.network
+        ? {
+            ...next,
+            network: {
+              ...next.network,
+              failed: next.network.failed.map((request) =>
+                request.excerpt === undefined
+                  ? request
+                  : { ...request, excerpt: request.excerpt.slice(0, 300) },
+              ),
+            },
+          }
+        : next,
+    (next) =>
+      next.errors
+        ? {
+            ...next,
+            errors: next.errors
+              .slice(0, 10)
+              .map((error) => (error.stack ? { ...error, stack: error.stack.slice(0, 4) } : error)),
+          }
+        : next,
+    (next) =>
+      without(
+        without(next.steps ? { ...next, steps: next.steps.slice(-15) } : next, "queries"),
+        "flags",
+      ),
+  ];
+  for (const cut of cuts) {
+    current = cut(current);
+    current.redaction = { ...current.redaction, truncated: true };
+    if (debugContextBytes(current) <= maxBytes) return current;
+  }
+  return current;
+}
+
+// ---------------------------------------------------------------- the brief
+
+export type BriefMeta = {
+  title?: string | null;
+  body?: string | null;
+  author?: string | null;
+  kind?: string | null;
+  createdAt?: string | null;
+  threadUrl?: string | null;
+  /** Other files on the thread, by name, so the brief can point at them. */
+  files?: readonly string[];
+};
+
+function ago(ms: number) {
+  const value = Math.abs(ms);
+  if (value < 1000) return `${Math.round(value)} ms`;
+  if (value < 60_000) return `${(value / 1000).toFixed(1)} s`;
+  if (value < 3_600_000) return `${Math.round(value / 60_000)} min`;
+  return `${(value / 3_600_000).toFixed(1)} h`;
+}
+
+function stepLine(step: DebugStep) {
+  switch (step.type) {
+    case "navigate":
+      return `went to ${step.path}`;
+    case "click":
+      return `clicked "${step.label}"`;
+    case "input":
+      return step.redacted
+        ? `typed in "${step.label}"`
+        : `typed "${step.value}" in "${step.label}"`;
+    case "console":
+      return `${step.level === "error" ? "error" : "warning"}: ${step.message}`;
+    case "network":
+      return step.status
+        ? `${step.method} ${step.path} answered ${step.status}`
+        : `${step.method} ${step.path} got no answer`;
+    case "say":
+      return `said "${step.text}"`;
+    default: {
+      const never: never = step;
+      return String(never);
+    }
+  }
+}
+
+function requestLine(request: DebugRequest, what: string) {
+  const ids = request.ids
+    ? Object.entries(request.ids)
+        .map(([name, id]) => `${name} ${id}`)
+        .join(", ")
+    : "";
+  const parts = [
+    `${ago(request.t)} before: ${request.method} ${request.url} ${what}${request.ms !== undefined ? ` in ${request.ms} ms` : ""}`,
+  ];
+  if (request.graphql?.errors.length) {
+    parts.push(
+      `   GraphQL${request.graphql.operation ? ` ${request.graphql.operation}` : ""} errors: ${request.graphql.errors.join("; ")}`,
+    );
+  }
+  if (request.excerpt) parts.push(`   ${request.excerpt.replace(/\s+/g, " ").slice(0, 400)}`);
+  if (ids) parts.push(`   (${ids})`);
+  return parts.join("\n");
+}
+
+function fence(text: string) {
+  return text.replace(/```/g, "ʼʼʼ");
+}
+
+/**
+ * The context as a short markdown brief for a coding agent: what was reported, where to look, what broke
+ * (newest first), the steps, the environment, and what else exists. The first three sections are always
+ * there, saying so when they are empty. Kept under about 6,000 tokens.
+ */
+export function debugContextBrief(file: DebugContextFile, meta: BriefMeta = {}): string {
+  const lines: string[] = [];
+  const on = new Set(file.signals);
+  const kind = meta.kind ? ` (${meta.kind})` : "";
+  const by = meta.author ? ` by ${meta.author}` : "";
+  const at = meta.createdAt ?? file.capturedAt;
+  const route = file.page?.routePattern ?? file.page?.route ?? "an unknown page";
+  lines.push("## Report");
+  const title = meta.title?.trim() || meta.body?.split("\n")[0]?.trim() || "Untitled report";
+  lines.push(
+    `"${fence(title.slice(0, 200))}"${kind}${by}, ${at.replace("T", " ").slice(0, 16)} UTC, on ${route}${file.page?.title ? ` (${file.page.title})` : ""}.`,
+  );
+  if (meta.body && meta.body.trim() !== title)
+    lines.push("", fence(meta.body.trim().slice(0, 1500)));
+  if (file.page?.url) lines.push("", `Page: ${file.page.url}`);
+  if (meta.threadUrl) lines.push(`Thread: ${meta.threadUrl}`);
+
+  lines.push("", "## Where to look");
+  const target = file.target;
+  if (target?.component || target?.file) {
+    const stack = target.stack?.length ? `, stack ${target.stack.join(" > ")}` : "";
+    const what =
+      target.role || target.name
+        ? `, ${target.role ?? "element"}${target.name ? ` "${target.name}"` : ""}`
+        : "";
+    lines.push(
+      `- Target: ${target.component ?? "component"}${target.file ? ` (${target.file})` : ""}${stack}${what}.`,
+    );
+  } else lines.push("- Target: the whole page (no element was pointed at).");
+  const host = file.build?.host;
+  if (host?.commit || host?.version) {
+    const stale = file.build?.staleHost
+      ? ` The tab runs an older build than the server serves (${host.deployed ?? "newer"}).`
+      : "";
+    const loaded =
+      file.page?.loadedAgoMs !== undefined
+        ? ` The page was loaded ${ago(file.page.loadedAgoMs)} before the report.`
+        : "";
+    lines.push(
+      `- Build: ${host.commit ? `commit ${host.commit}` : ""}${host.version ? `${host.commit ? ", " : ""}version ${host.version}` : ""}${host.env ? ` (${host.env})` : ""}.${loaded}${stale}`,
+    );
+  } else
+    lines.push(
+      `- Build: ${on.has("build") ? "the host app did not say which build it runs." : "not captured."}`,
+    );
+
+  lines.push("", "## What broke (newest first)");
+  type Item = { t: number; text: string };
+  const items: Item[] = [];
+  for (const request of file.network?.failed ?? []) {
+    items.push({
+      t: request.t,
+      text: requestLine(request, request.status ? `answered ${request.status}` : "got no answer"),
+    });
+  }
+  for (const error of file.errors ?? []) {
+    const count = error.count > 1 ? `, ${error.count} times` : "";
+    const where = error.stack?.[0] ?? error.source;
+    const component = error.componentStack?.length
+      ? `\n   in ${error.componentStack.slice(0, 5).join(" < ")}`
+      : "";
+    items.push({
+      t: error.t,
+      text: `${ago(error.t)} before${count}: ${error.kind === "console" ? `console.${error.level}` : error.kind} "${error.message}"${where ? ` at ${where}` : ""}${component}`,
+    });
+  }
+  items.sort((a, b) => b.t - a.t);
+  if (items.length)
+    items.slice(0, 15).forEach((item, index) => lines.push(`${index + 1}. ${fence(item.text)}`));
+  else if (on.has("errors") || on.has("network"))
+    lines.push("No errors or failed requests were recorded.");
+  else lines.push("Errors and requests were not captured.");
+  const pending = file.network?.pending ?? [];
+  if (pending.length)
+    lines.push(
+      `Still waiting when reported: ${pending
+        .slice(0, 5)
+        .map((request) => `${request.method} ${request.url} (${ago(request.t)})`)
+        .join("; ")}.`,
+    );
+  const slow = file.network?.slow ?? [];
+  if (slow.length)
+    lines.push(
+      `Slow: ${slow
+        .slice(0, 5)
+        .map((request) => `${request.method} ${request.url} ${request.ms ?? "?"} ms`)
+        .join("; ")}.`,
+    );
+  if (file.network?.aborted)
+    lines.push(`${file.network.aborted} request(s) were cancelled by the page.`);
+
+  if (file.steps?.length) {
+    const first = file.steps[0]!.t;
+    lines.push("", `## Steps (last ${ago(first)})`);
+    lines.push(fence(file.steps.slice(-40).map(stepLine).join(", ")) + ".");
+  }
+
+  lines.push("", "## Environment");
+  const client = file.client;
+  if (client) {
+    const parts = [
+      client.browser,
+      client.os ? `on ${client.os}` : undefined,
+      client.device,
+      client.appVersion
+        ? `app ${client.appVersion}${client.appBuild ? ` (${client.appBuild})` : ""}`
+        : undefined,
+      client.viewport
+        ? `${client.viewport[0]}×${client.viewport[1]}${client.dpr ? ` at ${client.dpr}x` : ""}`
+        : undefined,
+      client.locale,
+      client.timezone,
+      client.colorScheme ? `${client.colorScheme} mode` : undefined,
+      client.online === false ? "offline" : client.online ? "online" : undefined,
+      client.connection,
+    ].filter(Boolean);
+    lines.push(`${parts.join(", ")}.`);
+  } else lines.push("Not captured.");
+  const identity = file.identity;
+  if (identity) {
+    const who = [
+      identity.userId ? `User ${identity.userId}` : "A user",
+      identity.role ? `(${identity.role})` : undefined,
+      identity.orgId || identity.orgName
+        ? `in org ${identity.orgName ?? identity.orgId}${identity.orgName && identity.orgId ? ` (${identity.orgId})` : ""}`
+        : undefined,
+      identity.plan ? `on plan ${identity.plan}` : undefined,
+    ].filter(Boolean);
+    lines.push(`${who.join(" ")}.`);
+  }
+  if (file.flags) {
+    const flags = Object.entries(file.flags)
+      .slice(0, 30)
+      .map(
+        ([name, value]) =>
+          `${name}=${value === true ? "on" : value === false ? "off" : String(value)}`,
+      );
+    lines.push(`Flags: ${flags.join(", ")}.`);
+  }
+  if (file.realtime) {
+    const rt = file.realtime;
+    lines.push(
+      `Realtime: ${rt.status ?? "unknown"}${rt.lastMessageAgoMs !== undefined ? `, last message ${ago(rt.lastMessageAgoMs)} ago` : ""}${rt.reconnects ? `, ${rt.reconnects} reconnects` : ""}${rt.lastClose?.code ? `, last close ${rt.lastClose.code}${rt.lastClose.reason ? ` ${rt.lastClose.reason}` : ""}` : ""}.`,
+    );
+  }
+  const offline = file.lifecycle?.filter((event) => event.event === "offline").length ?? 0;
+  if (offline) lines.push(`Went offline ${offline} time(s) before the report.`);
+  if (file.performance) {
+    const p = file.performance;
+    const parts = [
+      p.longTasks !== undefined
+        ? `${p.longTasks} long tasks${p.longestTaskMs ? ` (longest ${Math.round(p.longestTaskMs)} ms)` : ""}`
+        : undefined,
+      p.inpMs !== undefined ? `worst interaction ${Math.round(p.inpMs)} ms` : undefined,
+      p.lcpMs !== undefined ? `LCP ${Math.round(p.lcpMs)} ms` : undefined,
+      p.cls !== undefined ? `CLS ${p.cls}` : undefined,
+      p.heapMb !== undefined ? `heap ${Math.round(p.heapMb)} MB` : undefined,
+    ].filter(Boolean);
+    if (parts.length) lines.push(`Performance: ${parts.join(", ")}.`);
+  }
+  const erroredQueries =
+    file.queries?.filter((query) => query.status === "error" || query.error) ?? [];
+  if (erroredQueries.length)
+    lines.push(
+      `Queries in error: ${erroredQueries
+        .slice(0, 5)
+        .map((query) => `${query.key}${query.error ? ` (${query.error})` : ""}`)
+        .join("; ")}.`,
+    );
+
+  lines.push("", "## More (fetch if needed)");
+  const more = [
+    "full context JSON",
+    file.target?.html ? "target DOM excerpt" : undefined,
+    file.queries?.length ? `${file.queries.length} cached queries` : undefined,
+    file.stores ? `store state (${Object.keys(file.stores).join(", ")})` : undefined,
+    file.storage ? "storage inventory" : undefined,
+    file.logs?.length ? `${file.logs.length} console lines` : undefined,
+    ...(meta.files ?? []).slice(0, 10),
+  ].filter(Boolean);
+  lines.push(`${more.join(", ")}.`);
+  const join = [
+    `report ${file.join.reportId}`,
+    file.join.traceId ? `trace ${file.join.traceId}` : undefined,
+    file.join.sessionId ? `session ${file.join.sessionId}` : undefined,
+  ].filter(Boolean);
+  lines.push(`Join ids: ${join.join(", ")}.`);
+  if (file.redaction.masked || file.redaction.dropped || file.redaction.truncated) {
+    lines.push(
+      `Redaction: ${file.redaction.masked} value(s) masked, ${file.redaction.dropped} dropped${file.redaction.truncated ? ", file trimmed to fit" : ""}. Missing values were removed on purpose.`,
+    );
+  }
+  const text = lines.join("\n");
+  return text.length > BRIEF_MAX_CHARS
+    ? `${text.slice(0, BRIEF_MAX_CHARS - 40)}\n\n(brief cut to fit)`
+    : text;
+}