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

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

@@ -0,0 +1,681 @@
+/**
+ * What every platform's debug context capture shares, with no DOM and no React Native: errors folded into
+ * counts, failed, slow and pending requests, the console's ordinary lines, going offline or to the
+ * background, what the host knows, the cache and stores, and turning all of it into the file. The web page
+ * (`./debug-context.ts`) and native apps (`@devaccel-labs/app-comments-native`) feed it from their own hooks.
+ *
+ * The hot path (`requestStarted`, `consoleCall`) does bookkeeping only. Reading a body, reading headers and
+ * redacting happen for failed or slow requests, after the app already has its answer.
+ */
+import {
+  fitDebugContext,
+  newReportId,
+  sanitizeDebugContext,
+  type DebugContextFile,
+  type DebugError,
+  type DebugErrorKind,
+  type DebugRequest,
+  type DebugSignal,
+  type DebugStep,
+  type HostBuild,
+  type HostContext,
+  type LifecycleEvent,
+  type ResolvedDebugContext,
+} from "./debug-context-model.js";
+import {
+  idHeaderNames,
+  newTally,
+  scrubId,
+  scrubText,
+  scrubUrl,
+  scrubValue,
+  type JsonBag,
+  type RedactionTally,
+} from "./debug-context-redact.js";
+import type { ReplayEvent } from "./replay-model.js";
+
+const MAX_ERRORS = 30;
+const MAX_FAILED = 30;
+const MAX_SLOW = 20;
+const MAX_PENDING = 50;
+const MAX_LOGS = 50;
+const MAX_LIFECYCLE = 30;
+const STEPS_WINDOW_MS = 180_000;
+const MAX_STEPS = 150;
+export const EXCERPT_CHARS = 2048;
+export const BODY_CHARS = 16_384;
+export const GRAPHQL_READ_CHARS = 65_536;
+const HOST_CONTEXT_TIMEOUT_MS = 300;
+
+/** Error messages every team ignores: browser noise, not the app's. */
+const NOISE = /^(?:ResizeObserver loop|Script error\.?$|Non-Error promise rejection captured)/;
+/** Frames from browser extensions and from the toolbar itself. */
+export const FOREIGN_FRAME = /(?:chrome|moz|safari(?:-web)?)-extension:\/\/|\/v1\/toolbar\//;
+/** Response types whose text is worth an excerpt. */
+export const TEXTUAL = /json|text|xml|javascript|graphql|x-www-form-urlencoded/i;
+
+export type DebugCaptureStats = { calls: number; ms: number };
+
+function stackLines(stack: string | undefined, message: string): string[] {
+  if (!stack) return [];
+  const out: string[] = [];
+  for (const raw of stack.split("\n")) {
+    const line = raw.trim();
+    if (!line || line === message || line.endsWith(`: ${message}`) || line === `Error: ${message}`)
+      continue;
+    if (FOREIGN_FRAME.test(line)) continue;
+    // Query strings in frame URLs can carry tokens (signed asset URLs); the path and position are enough.
+    out.push(scrubText(line.replace(/\?[^\s:)]*/g, "").replace(/^at\s+/, ""), 240));
+    if (out.length >= 12) break;
+  }
+  return out;
+}
+
+export function errorOf(value: unknown): { message: string; stack?: string } {
+  if (value instanceof Error)
+    return {
+      message: `${value.name && value.name !== "Error" ? `${value.name}: ` : ""}${value.message}`,
+      ...(value.stack ? { stack: value.stack } : {}),
+    };
+  if (typeof value === "string") return { message: value };
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof (value as { message?: unknown }).message === "string"
+  ) {
+    const shaped = value as { message: string; stack?: unknown };
+    return {
+      message: shaped.message,
+      ...(typeof shaped.stack === "string" ? { stack: shaped.stack } : {}),
+    };
+  }
+  return { message: value === undefined ? "undefined" : String(value) };
+}
+
+/** A console call's arguments as one line, with the stack of an `Error` among them. */
+export function argText(args: readonly unknown[]): { message: string; stack?: string } {
+  let stack: string | undefined;
+  const parts: string[] = [];
+  for (const arg of args) {
+    if (arg instanceof Error) {
+      parts.push(errorOf(arg).message);
+      stack ??= arg.stack;
+    } else if (typeof arg === "string" || typeof arg === "number" || typeof arg === "boolean") {
+      parts.push(String(arg));
+    } else if (arg && typeof arg === "object") {
+      // Small and redacted: a console line's object is often the most useful part, and also the riskiest.
+      try {
+        parts.push(JSON.stringify(scrubValue(arg, { depth: 2, entries: 10, text: 100 })));
+      } catch {
+        parts.push("[object]");
+      }
+    }
+    if (parts.join(" ").length > 2000) break;
+  }
+  return { message: parts.join(" ") || "error", ...(stack ? { stack } : {}) };
+}
+
+function matchesAny(url: string, patterns: readonly (string | RegExp)[] | undefined) {
+  if (!patterns?.length) return false;
+  return patterns.some((pattern) =>
+    typeof pattern === "string" ? url.startsWith(pattern) : pattern.test(url),
+  );
+}
+
+/** An excerpt with JSON keys that look sensitive masked; other text scrubbed as text. */
+export function excerptOf(text: string, max: number, tally: RedactionTally): string {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return scrubText(
+        JSON.stringify(
+          scrubValue(JSON.parse(trimmed), { depth: 5, entries: 30, text: 300, tally }),
+        ),
+        max,
+        tally,
+      );
+    } catch {
+      // Cut mid-way, so not parseable: fall through to text.
+    }
+  }
+  return scrubText(trimmed, max, tally);
+}
+
+export function graphqlErrors(text: string, tally: RedactionTally): string[] {
+  try {
+    const parsed = JSON.parse(text) as
+      | { errors?: Array<{ message?: unknown }> }
+      | Array<{ errors?: Array<{ message?: unknown }> }>;
+    const batches = Array.isArray(parsed) ? parsed : [parsed];
+    const out: string[] = [];
+    for (const batch of batches) {
+      for (const error of batch?.errors ?? []) {
+        if (typeof error?.message === "string") out.push(scrubText(error.message, 300, tally));
+        if (out.length >= 5) return out;
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function graphqlOperation(body: unknown): string | undefined {
+  if (typeof body !== "string" || body.length > 200_000) return undefined;
+  const named = /"operationName"\s*:\s*"([A-Za-z0-9_]{1,80})"/.exec(body)?.[1];
+  if (named) return named;
+  return /\b(?:query|mutation|subscription)\s+([A-Za-z0-9_]{1,80})/.exec(body)?.[1];
+}
+
+export function within<T>(promise: Promise<T> | T, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    Promise.resolve(promise).catch(() => undefined),
+    new Promise<undefined>((resolve) => {
+      timer = setTimeout(() => resolve(undefined), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+function stepOf(event: ReplayEvent, reportAt: number): DebugStep {
+  const t = event.t - reportAt;
+  switch (event.type) {
+    case "navigate":
+      return { t, type: "navigate", path: event.path };
+    case "click":
+      return { t, type: "click", label: event.label };
+    case "input":
+      return {
+        t,
+        type: "input",
+        label: event.label,
+        redacted: event.redacted,
+        ...(event.value ? { value: event.value } : {}),
+      };
+    case "console":
+      return { t, type: "console", level: event.level, message: event.message };
+    case "network":
+      return { t, type: "network", method: event.method, path: event.path, status: event.status };
+    case "say":
+      return { t, type: "say", text: event.text };
+    default: {
+      const never: never = event;
+      return never;
+    }
+  }
+}
+
+/**
+ * Replaces `host[key]` and returns the restore. The restore puts the original back only while ours is still
+ * installed, so a patch someone added after ours (Sentry, another tool) is never removed.
+ */
+export function patch<T extends object, K extends keyof T>(host: T, key: K, next: T[K]) {
+  const original = host[key];
+  host[key] = next;
+  return () => {
+    if (host[key] === next) host[key] = original;
+  };
+}
+
+/** How a platform reads a finished request: headers now, text only when asked (and only once). */
+export type RequestReaders = {
+  header: (name: string) => string | null;
+  /** The response's text, up to `max` characters. */
+  text?: (max: number) => Promise<string | null>;
+  /** The request's body as the app passed it. Only a string is ever kept. */
+  requestBody?: unknown;
+  /** The text could be read for a successful GraphQL request too (a 200 that holds errors). */
+  graphqlReadable?: boolean;
+};
+
+type Pending = { at: number; method: string; url: string };
+type Recorded = DebugRequest & { at: number };
+type ErrorEntry = Omit<DebugError, "t"> & { at: number };
+
+export type DebugCoreEnv = {
+  /** The address relative URLs are read against and same-origin URLs are shortened to. */
+  pageUrl: () => string | undefined;
+  /** Requests that are the toolbar's own (the comment service): never recorded. */
+  ignoreUrl?: (url: string) => boolean;
+  /** A high-resolution clock for `stats`. Default `Date.now`. */
+  clock?: () => number;
+};
+
+/** What every platform's file says the same way. */
+export type CoreSnapshot = Pick<
+  DebugContextFile,
+  | "errors"
+  | "logs"
+  | "network"
+  | "lifecycle"
+  | "steps"
+  | "queries"
+  | "stores"
+  | "realtime"
+  | "identity"
+  | "flags"
+  | "extra"
+  | "build"
+> & {
+  join: Pick<DebugContextFile["join"], "traceId" | "sessionId" | "requestIds">;
+  routePattern?: string;
+};
+
+export function createDebugCore(resolved: ResolvedDebugContext, env: DebugCoreEnv) {
+  const { signals, options, slowMs, audience } = resolved;
+  const ignoreUrl = env.ignoreUrl ?? (() => false);
+  const clock = env.clock ?? (() => Date.now());
+  const idNames = idHeaderNames(options.idHeaders ?? []);
+  const errors = new Map<string, ErrorEntry>();
+  const logs: Array<{ at: number; level: string; message: string }> = [];
+  const failed: Recorded[] = [];
+  const slow: Recorded[] = [];
+  const pending = new Map<number, Pending>();
+  const lifecycle: Array<{ at: number; event: LifecycleEvent }> = [];
+  const tally = newTally();
+  const stats: DebugCaptureStats = { calls: 0, ms: 0 };
+  let aborted = 0;
+  let nextId = 0;
+  let marked: number | null = null;
+  let markedPending: Pending[] | null = null;
+  let stopped = false;
+
+  /** Times our own bookkeeping, never the app's call. */
+  const timed = <T>(task: () => T): T => {
+    const started = clock();
+    try {
+      return task();
+    } finally {
+      stats.calls += 1;
+      stats.ms += clock() - started;
+    }
+  };
+
+  const pushError = (
+    kind: DebugErrorKind,
+    level: "error" | "warn",
+    rawMessage: string,
+    stack?: string,
+    source?: string,
+    componentStack?: string[],
+  ) => {
+    if (stopped || NOISE.test(rawMessage)) return;
+    const lines = stackLines(stack, rawMessage);
+    const message = scrubText(rawMessage, 500, tally);
+    const key = `${kind}|${message}|${lines[0] ?? source ?? ""}`;
+    const existing = errors.get(key);
+    const at = Date.now();
+    if (existing) {
+      existing.count += 1;
+      existing.at = at;
+      errors.delete(key);
+      errors.set(key, existing);
+      return;
+    }
+    if (errors.size >= MAX_ERRORS) {
+      const oldest = errors.keys().next().value;
+      if (oldest !== undefined) errors.delete(oldest);
+      tally.dropped += 1;
+    }
+    errors.set(key, {
+      at,
+      kind,
+      level,
+      message,
+      ...(lines.length ? { stack: lines } : {}),
+      ...(source ? { source: scrubText(source.replace(/\?[^\s:]*/g, ""), 240, tally) } : {}),
+      ...(componentStack?.length ? { componentStack } : {}),
+      count: 1,
+    });
+  };
+
+  const record = (list: Recorded[], max: number, entry: Recorded) => {
+    list.push(entry);
+    if (list.length > max) {
+      list.shift();
+      tally.dropped += 1;
+    }
+  };
+
+  const consoleCall = (
+    level: "error" | "warn" | "log" | "info" | "debug",
+    args: readonly unknown[],
+  ) => {
+    if (stopped) return;
+    if (level === "error" || level === "warn") {
+      if (!signals.errors) return;
+      const { message, stack } = argText(args);
+      pushError("console", level, message, stack);
+    } else if (signals.consoleLog) {
+      logs.push({ at: Date.now(), level, message: scrubText(argText(args).message, 300, tally) });
+      if (logs.length > MAX_LOGS) logs.shift();
+    }
+  };
+
+  const requestStarted = (method: string, url: string): number | null => {
+    if (stopped || !signals.network || ignoreUrl(url)) return null;
+    const id = ++nextId;
+    if (pending.size < MAX_PENDING)
+      pending.set(id, { at: Date.now(), method: method.toUpperCase(), url });
+    return id;
+  };
+
+  const requestAborted = (id: number) => {
+    pending.delete(id);
+    aborted += 1;
+  };
+
+  const requestFinished = (id: number, status: number, readers: RequestReaders) => {
+    const entry = pending.get(id);
+    pending.delete(id);
+    if (!entry || stopped) return;
+    const ms = Math.round(Date.now() - entry.at);
+    const isFailed = status === 0 || status >= 400;
+    const isSlow = !isFailed && ms >= slowMs;
+    const graphqlCandidate =
+      !isFailed && readers.graphqlReadable === true && /graphql/i.test(entry.url);
+    if (!isFailed && !isSlow && !graphqlCandidate) return;
+    const request: Recorded = {
+      at: entry.at,
+      t: 0,
+      method: entry.method,
+      url: scrubUrl(entry.url, 400, env.pageUrl(), tally),
+      status,
+      ms,
+    };
+    const contentType = readers.header("content-type");
+    if (contentType) request.contentType = contentType.split(";")[0]!.trim().slice(0, 80);
+    const length = Number(readers.header("content-length"));
+    if (Number.isFinite(length) && length > 0) request.bytes = length;
+    const ids: Record<string, string> = {};
+    for (const name of idNames) {
+      const value = readers.header(name);
+      if (value) ids[name] = scrubId(value);
+    }
+    if (Object.keys(ids).length) request.ids = ids;
+    const operation = graphqlOperation(readers.requestBody);
+    const bodies = signals.bodies && matchesAny(entry.url, options.bodyUrls);
+    if (bodies && typeof readers.requestBody === "string")
+      request.requestBody = excerptOf(readers.requestBody, BODY_CHARS, tally);
+    if (isFailed || isSlow)
+      record(isFailed ? failed : slow, isFailed ? MAX_FAILED : MAX_SLOW, request);
+    const textual = !contentType || TEXTUAL.test(contentType);
+    if (isFailed && readers.text && textual && (signals.responseExcerpts || bodies)) {
+      void readers.text(bodies ? BODY_CHARS : EXCERPT_CHARS).then((text) => {
+        if (!text) return;
+        if (signals.responseExcerpts)
+          request.excerpt = excerptOf(text.slice(0, EXCERPT_CHARS), EXCERPT_CHARS, tally);
+        if (bodies) request.responseBody = excerptOf(text, BODY_CHARS, tally);
+        if (operation) {
+          const found = graphqlErrors(text, tally);
+          if (found.length) request.graphql = { operation, errors: found };
+        }
+      });
+    }
+    if (graphqlCandidate && readers.text && contentType && /json/i.test(contentType)) {
+      void readers.text(GRAPHQL_READ_CHARS).then((text) => {
+        const found = text && text.length < GRAPHQL_READ_CHARS ? graphqlErrors(text, tally) : [];
+        if (found.length) {
+          request.graphql = { ...(operation ? { operation } : {}), errors: found };
+          record(failed, MAX_FAILED, request);
+        }
+      });
+    }
+  };
+
+  const noteLifecycle = (event: LifecycleEvent) => {
+    if (stopped || !signals.lifecycle) return;
+    lifecycle.push({ at: Date.now(), event });
+    if (lifecycle.length > MAX_LIFECYCLE) lifecycle.shift();
+  };
+
+  const reportError = (error: unknown, componentStack?: string | null) => {
+    if (!signals.componentStacks || stopped) return;
+    timed(() => {
+      const { message, stack } = errorOf(error);
+      const components = (componentStack ?? "")
+        .split("\n")
+        .map((line) =>
+          line
+            .trim()
+            .replace(/^at\s+/, "")
+            .split(" (")[0]!
+            .trim(),
+        )
+        .filter(Boolean)
+        .slice(0, 12)
+        .map((line) => scrubText(line, 120, tally));
+      pushError("boundary", "error", message, stack, undefined, components);
+    });
+  };
+
+  const hostContext = async (): Promise<HostContext | undefined> => {
+    if (!options.getContext) return undefined;
+    if (!signals.host && !signals.build && !signals.realtime && !signals.staleBuild)
+      return undefined;
+    try {
+      const value = await within(options.getContext(), HOST_CONTEXT_TIMEOUT_MS);
+      return value && typeof value === "object" ? value : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  /** The sections every platform writes the same way, for a report taken at `reportAt`. */
+  const shared = async (
+    reportAt: number,
+    steps: readonly ReplayEvent[] | undefined,
+    fileTally: RedactionTally,
+    toolbarBuild?: string,
+  ): Promise<CoreSnapshot> => {
+    const on = (signal: DebugSignal) => signals[signal];
+    const relative = (at: number) => Math.round(at - reportAt);
+    const host = await hostContext();
+    const out: CoreSnapshot = { join: {} };
+
+    if (on("build") || on("staleBuild")) {
+      const merged: HostBuild = { ...options.build, ...host?.build };
+      const current = merged.commit ?? merged.version;
+      out.build = {
+        ...(Object.keys(merged).length && on("build") ? { host: merged } : {}),
+        ...(toolbarBuild ? { toolbar: toolbarBuild } : {}),
+        ...(on("staleBuild") && merged.deployed && current
+          ? { staleHost: merged.deployed !== current }
+          : {}),
+      };
+    }
+    if (on("host") && host) {
+      const identity = {
+        ...(host.user?.id ? { userId: String(host.user.id) } : {}),
+        ...(host.user?.role ? { role: String(host.user.role) } : {}),
+        ...(host.user?.plan ? { plan: String(host.user.plan) } : {}),
+        ...(host.user?.locale ? { locale: String(host.user.locale) } : {}),
+        ...(host.org?.id ? { orgId: String(host.org.id) } : {}),
+        ...(host.org?.name ? { orgName: String(host.org.name) } : {}),
+      };
+      if (Object.keys(identity).length) out.identity = identity;
+      if (host.flags) out.flags = host.flags;
+      if (host.extra) out.extra = host.extra;
+      if (host.traceId) out.join.traceId = String(host.traceId);
+      if (host.sessionId) out.join.sessionId = String(host.sessionId);
+      if (typeof host.routePattern === "string")
+        out.routePattern = scrubText(host.routePattern, 200, fileTally);
+    }
+    if (on("realtime") && host?.realtime) {
+      const rt = host.realtime;
+      out.realtime = {
+        ...(rt.status ? { status: rt.status } : {}),
+        ...(typeof rt.lastMessageAt === "number"
+          ? { lastMessageAgoMs: Math.max(0, reportAt - rt.lastMessageAt) }
+          : {}),
+        ...(typeof rt.reconnects === "number" ? { reconnects: rt.reconnects } : {}),
+        ...(rt.lastClose ? { lastClose: rt.lastClose } : {}),
+      };
+    }
+    if (errors.size)
+      out.errors = [...errors.values()].map(({ at, ...rest }) => ({ ...rest, t: relative(at) }));
+    if (logs.length) out.logs = logs.map(({ at, ...rest }) => ({ ...rest, t: relative(at) }));
+    if (on("network")) {
+      const still = markedPending ?? [...pending.values()];
+      const strip = ({ at, ...rest }: Recorded): DebugRequest => ({ ...rest, t: relative(at) });
+      out.network = {
+        failed: failed.map(strip),
+        slow: slow.map(strip),
+        pending: still.slice(-20).map((entry) => ({
+          t: relative(entry.at),
+          method: entry.method,
+          url: scrubUrl(entry.url, 400, env.pageUrl(), fileTally),
+          status: 0,
+        })),
+        aborted,
+      };
+      const requestIds = [
+        ...new Set([...failed, ...slow].flatMap((request) => Object.values(request.ids ?? {}))),
+      ].slice(0, 30);
+      if (requestIds.length) out.join.requestIds = requestIds;
+    }
+    if (on("steps") && steps?.length) {
+      out.steps = steps
+        .filter((step) => step.t >= reportAt - STEPS_WINDOW_MS && step.t <= reportAt + 1000)
+        .slice(-MAX_STEPS)
+        .map((step) => stepOf(step, reportAt));
+    }
+    if (on("lifecycle") && lifecycle.length)
+      out.lifecycle = lifecycle.map(({ at, event }) => ({ t: relative(at), event }));
+    if (on("queries") && options.queries) {
+      try {
+        out.queries = options
+          .queries()
+          .slice(0, 50)
+          .map((query) => {
+            const error =
+              query.error === undefined || query.error === null
+                ? undefined
+                : errorOf(query.error).message;
+            return {
+              key: scrubText(
+                JSON.stringify(
+                  scrubValue(query.key, { depth: 3, entries: 10, text: 80, tally: fileTally }),
+                ) ?? "",
+                200,
+                fileTally,
+              ),
+              ...(query.status ? { status: String(query.status) } : {}),
+              ...(query.fetchStatus ? { fetchStatus: String(query.fetchStatus) } : {}),
+              ...(error ? { error: scrubText(error, 300, fileTally) } : {}),
+              ...(typeof query.updatedAt === "number" && query.updatedAt > 0
+                ? { updatedAgoMs: Math.max(0, reportAt - query.updatedAt) }
+                : {}),
+              ...(typeof query.observers === "number" ? { observers: query.observers } : {}),
+            };
+          });
+      } catch {
+        fileTally.dropped += 1;
+      }
+    }
+    if (on("stores") && options.stores) {
+      const stores: JsonBag = {};
+      for (const [name, read] of Object.entries(options.stores).slice(0, 10)) {
+        try {
+          stores[name] = scrubValue(read(), {
+            depth: on("storeValues") ? 6 : 4,
+            entries: 50,
+            text: 300,
+            shapeOnly: !on("storeValues"),
+            tally: fileTally,
+          });
+        } catch {
+          fileTally.dropped += 1;
+        }
+      }
+      if (Object.keys(stores).length) out.stores = stores;
+    }
+    return out;
+  };
+
+  /**
+   * The report: a new id, the host told it, the host's `beforeCapture` (fail closed), redacted again and
+   * bounded. `build` adds the platform's own sections to the shared ones.
+   */
+  const finish = (file: DebugContextFile, fileTally: RedactionTally): DebugContextFile | null => {
+    file.redaction.masked = tally.masked + fileTally.masked;
+    file.redaction.dropped = tally.dropped + fileTally.dropped;
+    try {
+      options.onReport?.(file.join.reportId);
+    } catch {
+      // The host's logger failing must not lose the report.
+    }
+    let final: DebugContextFile | null = file;
+    if (options.beforeCapture) {
+      try {
+        final = options.beforeCapture(file);
+      } catch {
+        // Fail closed: a sanitizer that throws sends nothing.
+        return null;
+      }
+    }
+    if (!final) return null;
+    const clean = sanitizeDebugContext(final);
+    return clean ? fitDebugContext(clean) : null;
+  };
+
+  /** A file with the fields every report has, for `reportAt`. */
+  const skeletonFile = (
+    reportAt: number,
+    platform: DebugContextFile["platform"],
+  ): DebugContextFile => ({
+    v: 1,
+    kind: "debug-context",
+    capturedAt: new Date(reportAt).toISOString(),
+    audience,
+    platform,
+    join: { reportId: newReportId() },
+    signals: (Object.keys(signals) as DebugSignal[]).filter((signal) => signals[signal]),
+    redaction: { rules: 1, masked: 0, dropped: 0, truncated: false },
+  });
+
+  return {
+    signals,
+    options,
+    tally,
+    timed,
+    pushError,
+    consoleCall,
+    requestStarted,
+    requestFinished,
+    requestAborted,
+    noteLifecycle,
+    reportError,
+    shared,
+    finish,
+    skeletonFile,
+    get stopped() {
+      return stopped;
+    },
+    mark() {
+      marked = Date.now();
+      markedPending = [...pending.values()];
+    },
+    /** The report's moment: the mark, or now. Clears the mark. */
+    takeMark(): number {
+      const at = marked ?? Date.now();
+      return at;
+    },
+    clearMark() {
+      marked = null;
+      markedPending = null;
+    },
+    stats: (): DebugCaptureStats => ({ ...stats }),
+    stop() {
+      stopped = true;
+      errors.clear();
+      failed.length = 0;
+      slow.length = 0;
+      pending.clear();
+      logs.length = 0;
+      lifecycle.length = 0;
+    },
+  };
+}
+
+export type DebugCore = ReturnType<typeof createDebugCore>;