@debugbundle/sdk-react-native 3.0.1 → 3.1.0

package/src/exception-evidence.ts

@@ -0,0 +1,112 @@
+import { errorField, safeErrorStack, nativeBrand } from "./safe-error-fields.js";
+import { sanitizeValue } from "./redaction.js";
+import { utf8Bytes } from "./owned-json.js";
+
+type LegacyError = { name: string; message: string; stack: string; traceAvailable?: boolean };
+type Frame = { function: string | null; file: string | null; line: number | null; column: number | null; classification: "unknown" | "framework" | "sdk" };
+type Node = { id: number; name: string; message: string; stack: string | null; trace_origin: string; parsing_status: string;
+  frames: Frame[]; relationships: Array<{ kind: "cause"; target_id: number }> };
+const text = (value: unknown, fallback: string): string => typeof value === "string" && value ? value : fallback;
+export function snapshotError(error: unknown, fields: string[]): LegacyError {
+  let name = "Error", message = "Unknown error", stack: unknown;
+  try {
+    if (typeof error === "string") message = error;
+    else if (error !== null && typeof error === "object") {
+      name = text(errorField(error, "name"), name); message = text(errorField(error, "message"), message); stack = safeErrorStack(error);
+    }
+  } catch { /* Legacy outer evidence is best effort; no application accessor is required. */ }
+  return {
+    name: text(sanitizeValue(name, { redactFields: fields }), "Error"),
+    message: text(sanitizeValue(message, { redactFields: fields }), "Unknown error"),
+    stack: text(sanitizeValue(text(stack, `${name}: ${message}`), { redactFields: fields, maxStringLength: 8192 }), `${name}: ${message}`),
+    traceAvailable: typeof stack === "string" && stack.length > 0
+  };
+}
+
+function clip(text: string, maximum: number): string {
+  let result = "", bytes = 0;
+  for (const character of text.slice(0, maximum)) {
+    const cost = utf8Bytes(character); if (bytes + cost > maximum) break;
+    result += character; bytes += cost;
+  }
+  return result;
+}
+export function parseMobileStack(stack: string, maximum = 32): { frames: Frame[]; status: string; truncated: boolean } {
+  const frames: Frame[] = [];
+  const lines = stack.slice(0, 16_384).split(/\r?\n/, 129);
+  let partial = false, truncated = stack.length > 16_384 || lines.length > 128;
+  for (const input of lines.slice(0, 128)) {
+    if (frames.length >= maximum) { truncated = true; break; }
+    if (input.length > 2048) truncated = true;
+    const line = input.trim().slice(0, 2048);
+    const named = /^at\s+(.+?)\s*\((?:address at )?(.+?):(\d+)(?::(\d+))?\)$/.exec(line);
+    const anonymous = named ? null : /^at\s+(.+?):(\d+)(?::(\d+))?$/.exec(line);
+    const webkit = named || anonymous ? null : /^(.*?)@(.+?):(\d+)(?::(\d+))?$/.exec(line);
+    const match = named ?? anonymous ?? webkit;
+    if (!match) { if (/^at\s|@\S+:\d/.test(line)) partial = true; continue; }
+    let file = named || webkit ? match[2]! : match[1]!;
+    if (/^https?:\/\//i.test(file)) {
+      try { const url = new URL(file); file = `${url.protocol}//${url.host}${url.pathname}`; } catch { partial = true; continue; }
+    } else file = file.split(/[?#]/, 1)[0]!;
+    const row = Number(named || webkit ? match[3] : match[2]);
+    const rawColumn = named || webkit ? match[4] : match[3];
+    const column = rawColumn === undefined ? null : Number(rawColumn);
+    if (!Number.isSafeInteger(row) || row <= 0 || column !== null && (!Number.isSafeInteger(column) || column < 0)) { partial = true; continue; }
+    const fn = named || webkit ? clip(match[1]!.trim(), 256) || null : null;
+    frames.push({ function: fn, file: clip(file, 2048), line: row, column,
+      classification: /node_modules[/\\]@debugbundle[/\\]/.test(file) ? "sdk" : /node_modules[/\\]/.test(file) ? "framework" : "unknown" });
+  }
+  return { frames, status: truncated ? "truncated" : !frames.length ? "unparsed" : partial ? "partial" : "parsed", truncated };
+}
+
+function stackLinks(stack: string): string {
+  return stack.replace(/https?:\/\/[^\s)]+/gi, source => {
+    const coordinate = /(:\d+(?::\d+)?)$/.exec(source)?.[1] ?? "";
+    const location = coordinate ? source.slice(0, -coordinate.length) : source;
+    try { const url = new URL(location); return `${url.protocol}//${url.host}${url.pathname}${coordinate}`; } catch { return "[unavailable URL]"; }
+  });
+}
+
+/** New cause traversal requires the engine's native Error brand. Hermes/JSC
+ * without it retain the outer error and explicitly report unsupported traversal.
+ * Portable JS cannot prove aggregate arrays are not proxies: no iterator is run. */
+export function snapshotExceptionEvidence(error: unknown, legacy: LegacyError, fields: string[], fatal = false,
+  brand = nativeBrand): Record<string, unknown> | undefined {
+  const nodes: Node[] = [], seen = new Map<object, number>(), active = new Set<object>();
+  let unsupported = brand === undefined, unsafe = false, truncated = false, totalFrames = 0;
+  const visit = (value: unknown, depth: number, root = false): number | null => {
+    if (!root && (!brand || !brand(value))) { unsupported = true; return null; }
+    if (typeof value === "object" && value !== null && active.has(value)) { truncated = true; return null; }
+    if (depth > (fatal ? 1 : 4) || nodes.length >= (fatal ? 2 : 8)) { truncated = true; return null; }
+    if (!root && seen.has(value as object)) return seen.get(value as object)!;
+    const snapshot = root ? legacy : snapshotError(value, fields);
+    const name = clip(snapshot.name, 256), message = clip(snapshot.message, fatal ? 512 : 2048);
+    const stack = stackLinks(clip(snapshot.stack, fatal ? 512 : 16_384));
+    const parsed = parseMobileStack(stack, fatal ? Math.min(4, 8 - totalFrames) : 32), frames = parsed.frames;
+    totalFrames += frames.length; truncated ||= parsed.truncated;
+    const trace = snapshot.traceAvailable !== false;
+    const id = nodes.length;
+    const node: Node = { id, name, message, stack: trace ? stack : null, frames: trace ? frames : [],
+      trace_origin: trace ? "runtime_reported" : "unavailable", parsing_status: trace ? parsed.status : "unavailable", relationships: [] };
+    nodes.push(node);
+    if (!brand || !brand(value)) { unsupported = true; return id; }
+    seen.set(value as object, id); active.add(value as object);
+    const cause = Object.getOwnPropertyDescriptor(value, "cause");
+    if (cause && !("value" in cause)) unsafe = true;
+    else if (cause?.value !== undefined) { const target = visit(cause.value, depth + 1); if (target !== null) node.relationships.push({ kind: "cause", target_id: target }); }
+    const aggregate = Object.getOwnPropertyDescriptor(value, "errors");
+    if (aggregate) { if (!("value" in aggregate)) unsafe = true; else unsupported = true; }
+    active.delete(value as object); return id;
+  };
+  try { visit(error, 0, true); } catch { unsafe = true; }
+  if (!nodes.length) return undefined;
+  const graph = { version: 1, runtime: "react_native", root_id: 0, nodes, truncated,
+    unavailable_reason: unsafe ? "unsafe" : truncated ? "budget_exceeded" : unsupported ? "unsupported" : null };
+  const maximum = fatal ? 3584 : 31_000;
+  if (utf8Bytes(JSON.stringify(graph)) > maximum) {
+    graph.truncated = true; graph.unavailable_reason = "budget_exceeded";
+    for (const node of nodes) { node.stack = null; node.frames = node.frames.slice(0, fatal ? 2 : 4); node.parsing_status = "truncated"; }
+  }
+  if (utf8Bytes(JSON.stringify(graph)) > maximum) for (const node of nodes) node.frames = [];
+  return utf8Bytes(JSON.stringify(graph)) <= maximum ? graph : undefined;
+}

package/src/index.ts

@@ -12,10 +12,15 @@ import type {
   DebugBundleResponseInfo,
   DebugBundleStatus
 } from "./types.js";
+import type { EvidenceCapabilities, OperationScope, RecoveryObservation } from "./evidence-types.js";
 
 const singleton = new DebugBundleReactNativeClient();
 
 export const DebugBundle = {
+  beginOperation(): OperationScope { return singleton.beginOperation(); },
+  withOperationContext<T>(operation: (scope: OperationScope) => T): T { return singleton.withOperationContext(operation); },
+  captureRecovery(observation: RecoveryObservation): void { singleton.captureRecovery(observation); },
+  get evidenceCapabilities(): EvidenceCapabilities { return singleton.evidenceCapabilities; },
   init(config: DebugBundleConfig): void {
     singleton.init(config);
     if (config.captureErrors !== false) {
@@ -71,6 +76,7 @@ export const DebugBundle = {
 export { createDebugBundleClient, DebugBundleReactNativeClient };
 export { captureDebugBundleConsole };
 export { installDebugBundleErrorHandlers };
+export type { EvidenceCapabilities, EvidenceFeature, EvidenceScope, OperationScope, RecoveryObservation } from "./evidence-types.js";
 export type {
   DebugBundleCaptureContext,
   DebugBundleBeforeSend,

package/src/owned-json.ts

@@ -0,0 +1,60 @@
+export type OwnedJSON = null | boolean | number | string | OwnedJSON[] | { [key: string]: OwnedJSON };
+
+/** Exhausted ownership cannot safely fall back to pre-hook application data. */
+export class EventValidationUnavailable extends Error {}
+
+export function utf8Bytes(value: string): number {
+  let bytes = 0;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code < 0x80) bytes++;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length &&
+      value.charCodeAt(index + 1) >= 0xdc00 && value.charCodeAt(index + 1) <= 0xdfff) { bytes += 4; index++; }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+/** Bounded plain JSON copy; no toJSON, property getters, foreign iterators or formatters. */
+export function ownJSON(input: unknown): OwnedJSON {
+  let nodes = 4096, remaining = 8 * 1024 * 1024;
+  const seen = new Set<object>();
+  const use = (amount: number): void => { remaining -= amount; if (remaining < 0) throw new EventValidationUnavailable(); };
+  const visit = (value: unknown, depth: number): OwnedJSON => {
+    if (--nodes < 0 || depth > 16) throw new EventValidationUnavailable();
+    if (value === null || typeof value === "boolean") { use(5); return value; }
+    if (typeof value === "number" && Number.isFinite(value)) { use(24); return value; }
+    if (typeof value === "string") { if (value.length > remaining) throw new EventValidationUnavailable(); use(utf8Bytes(value) + 2); return value; }
+    if (typeof value !== "object" || value === null || seen.has(value)) throw new TypeError("invalid JSON");
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        if (value.length > 256) throw new EventValidationUnavailable();
+        use(value.length + 2);
+        return Array.from({ length: value.length }, (_, index) => {
+          const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+          if (!descriptor || !("value" in descriptor)) throw new TypeError("invalid JSON");
+          return visit(descriptor.value, depth + 1);
+        });
+      }
+      if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError("invalid JSON");
+      const keys = Object.keys(value);
+      if (keys.length > 256) throw new EventValidationUnavailable();
+      const output: Record<string, OwnedJSON> = Object.create(null);
+      for (const key of keys) {
+        if (key.length > remaining) throw new EventValidationUnavailable();
+        use(utf8Bytes(key) + 4);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor)) throw new TypeError("invalid JSON");
+        output[key] = visit(descriptor.value, depth + 1);
+      }
+      return output;
+    } finally { seen.delete(value); }
+  };
+  return visit(input, 0);
+}
+
+export function jsonObject(value: unknown): Record<string, OwnedJSON> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, OwnedJSON> : null;
+}

package/src/privacy-keys.ts

@@ -19,12 +19,22 @@ function splitKeyIntoSegments(key: string): string[] {
 }
 
 export function isSensitiveKey(key: string, sensitiveKeys: readonly string[]): boolean {
+  return createSensitiveKeyMatcher(sensitiveKeys)(key);
+}
+
+/** Operation-owned lookup: bounded caller policy never enters a global cache. */
+export function createSensitiveKeyMatcher(sensitiveKeys: readonly string[]): (key: string) => boolean {
+  const exact = new Set(sensitiveKeys);
+  const canonicalSensitiveKeys = new Set(sensitiveKeys.map(canonicalizeSensitiveKey));
+  return key => matchesSensitiveKey(key, exact, canonicalSensitiveKeys);
+}
+
+function matchesSensitiveKey(key: string, exact: ReadonlySet<string>, canonicalSensitiveKeys: ReadonlySet<string>): boolean {
   const normalized = key.trim().toLowerCase();
-  if (sensitiveKeys.includes(normalized)) {
+  if (exact.has(normalized)) {
     return true;
   }
 
-  const canonicalSensitiveKeys = new Set(sensitiveKeys.map(canonicalizeSensitiveKey));
   const segments = splitKeyIntoSegments(key);
   for (let start = 0; start < segments.length; start += 1) {
     let combined = "";

package/src/privacy-telemetry.ts

@@ -1,6 +1,6 @@
 type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
-import { DEFAULT_SENSITIVE_KEYS, isSensitiveKey } from "./privacy-keys.js";
-import { scrubCredentialText } from "./privacy-text.js";
+import { DEFAULT_SENSITIVE_KEYS, createSensitiveKeyMatcher } from "./privacy-keys.js";
+import { createCredentialTextScrubber } from "./privacy-text.js";
 
 const REDACTED = "[REDACTED]";
 const MAX_DEPTH = 16;
@@ -23,8 +23,8 @@ interface WorkState {
   textBytes: number;
   redactionCount: number;
   seen: WeakSet<object>;
-  keys: string[];
-  extra: readonly string[];
+  sensitiveKey: (key: string) => boolean;
+  scrubText: (value: string) => string;
   maxTotalBytes: number;
 }
 
@@ -72,7 +72,7 @@ function sanitizeString(value: string, state: WorkState, allowStructured: boolea
     }
   }
 
-  const result = scrubCredentialText(value, state.extra);
+  const result = state.scrubText(value);
   if (result !== value) state.redactionCount += 1;
   if ((value.startsWith("{") || value.startsWith("[")) && result === value &&
       /(?:password|token|secret|authorization|cookie)["']?\s*[:=]/i.test(value)) {
@@ -114,14 +114,14 @@ function sanitizeValue(value: unknown, state: WorkState, depth: number, allowStr
       }
       state.textBytes += byteLength(key);
       if (state.textBytes > state.maxTotalBytes) throw new BudgetExceeded();
-      const safeKey = scrubCredentialText(key, state.extra);
+      const safeKey = state.scrubText(key);
       if (safeKey !== key) {
         state.redactionCount += 1;
         continue;
       }
       const descriptor = Object.getOwnPropertyDescriptor(value, key);
       if (descriptor === undefined || !("value" in descriptor)) throw new TypeError("unsafe_input");
-      const safeValue = isSensitiveKey(key, state.keys)
+      const safeValue = state.sensitiveKey(key)
         ? mask(state)
         : sanitizeValue(descriptor.value, state, depth + 1, allowStructured);
       Object.defineProperty(result, key, {
@@ -153,8 +153,8 @@ export function sanitizeTelemetry(value: unknown, options: TelemetrySanitization
       textBytes: 0,
       redactionCount: 0,
       seen: new WeakSet<object>(),
-      keys: [...DEFAULT_SENSITIVE_KEYS, ...extra],
-      extra,
+      sensitiveKey: createSensitiveKeyMatcher([...DEFAULT_SENSITIVE_KEYS, ...extra]),
+      scrubText: createCredentialTextScrubber(extra),
       maxTotalBytes
     };
     const sanitized = sanitizeValue(value, state, 0, true);

package/src/privacy-text.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_SENSITIVE_KEYS, isSensitiveKey } from "./privacy-keys.js";
+import { DEFAULT_SENSITIVE_KEYS, createSensitiveKeyMatcher } from "./privacy-keys.js";
 
 const REDACTED = "[REDACTED]";
 const BUILTIN_LABELS = [...DEFAULT_SENSITIVE_KEYS, "client_secret", "x_api_key",
@@ -34,7 +34,7 @@ function isValidCard(value: string): boolean {
   return sum % 10 === 0;
 }
 
-function scrubUrl(raw: string, keys: readonly string[]): string {
+function scrubUrl(raw: string, scrub: (value: string, scanUrls?: boolean) => string, sensitive: (key: string) => boolean): string {
   try {
     const url = new URL(raw);
     if (url.username || url.password) {
@@ -43,8 +43,8 @@ function scrubUrl(raw: string, keys: readonly string[]): string {
     }
     const nextQuery = new URLSearchParams();
     for (const [key, value] of url.searchParams) {
-      if (key.length > 128 || scrubCredentialText(key, keys, false) !== key) continue;
-      nextQuery.append(key, isSensitiveKey(key, keys) || scrubCredentialText(value, keys, false) !== value ? REDACTED : value);
+      if (key.length > 128 || scrub(key, false) !== key) continue;
+      nextQuery.append(key, sensitive(key) || scrub(value, false) !== value ? REDACTED : value);
     }
     url.search = nextQuery.toString();
     url.hash = "";
@@ -55,32 +55,33 @@ function scrubUrl(raw: string, keys: readonly string[]): string {
   }
 }
 
-/** Bounded caller input only. Returns stable replacement text, never the matching secret. */
-export function scrubCredentialText(input: string, additionalKeys: readonly string[], scanUrls = true): string {
-  const keys = [...DEFAULT_SENSITIVE_KEYS, ...additionalKeys];
-  if (PEM_START.test(input) && !PEM_COMPLETE.test(input)) return REDACTED;
-  let output = input;
-  if (/(?:password|token|secret|authorization|cookie)%3[ad]/i.test(output)) {
-    try {
-      output = decodeURIComponent(output);
-    } catch {
-      return REDACTED;
-    }
-  }
-  output = output.replace(PEM, REDACTED).replace(HEADER, "$1: [REDACTED]");
-  output = output.replace(BEARER, "$1 [REDACTED]").replace(DEBUGBUNDLE_TOKEN, REDACTED);
-  output = output.replace(ASSIGNMENT, "$1$2[REDACTED]");
-  if (additionalKeys.length > 0) {
-    for (const key of additionalKeys) {
-      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const named = new RegExp(`\\b(${escaped})\\b(["']?\\s*[:=]\\s*)(?:"[^"]*"|'[^']*'|[^\\s&,;]+)`, "gi");
-      output = output.replace(named, "$1$2[REDACTED]");
-    }
-  }
-  output = output.replace(CARD, (candidate) => isValidCard(candidate) ? REDACTED : candidate);
-  if (!scanUrls) return output;
-  return output.replace(URL_TEXT, (matched) => {
-    const trailing = matched.match(/[).,;]+$/)?.[0] ?? "";
-    return scrubUrl(matched.slice(0, matched.length - trailing.length), keys) + trailing;
+/** Compile each caller rule once per bounded protection operation, not per scalar. */
+export function createCredentialTextScrubber(additionalKeys: readonly string[]): (input: string, scanUrls?: boolean) => string {
+  const sensitive = createSensitiveKeyMatcher([...DEFAULT_SENSITIVE_KEYS, ...additionalKeys]);
+  const patterns = additionalKeys.map(key => {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`\\b(${escaped})\\b(["']?\\s*[:=]\\s*)(?:"[^"]*"|'[^']*'|[^\\s&,;]+)`, "gi");
   });
+  const scrub = (input: string, scanUrls = true): string => {
+    if (PEM_START.test(input) && !PEM_COMPLETE.test(input)) return REDACTED;
+    let output = input;
+    if (/(?:password|token|secret|authorization|cookie)%3[ad]/i.test(output)) {
+      try {
+        output = decodeURIComponent(output);
+      } catch {
+        return REDACTED;
+      }
+    }
+    output = output.replace(PEM, REDACTED).replace(HEADER, "$1: [REDACTED]");
+    output = output.replace(BEARER, "$1 [REDACTED]").replace(DEBUGBUNDLE_TOKEN, REDACTED);
+    output = output.replace(ASSIGNMENT, "$1$2[REDACTED]");
+    for (const pattern of patterns) output = output.replace(pattern, "$1$2[REDACTED]");
+    output = output.replace(CARD, (candidate) => isValidCard(candidate) ? REDACTED : candidate);
+    if (!scanUrls) return output;
+    return output.replace(URL_TEXT, (matched) => {
+      const trailing = matched.match(/[).,;]+$/)?.[0] ?? "";
+      return scrubUrl(matched.slice(0, matched.length - trailing.length), scrub, sensitive) + trailing;
+    });
+  };
+  return scrub;
 }

package/src/redaction.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_SENSITIVE_KEYS, isSensitiveKey as privacySensitiveKey } from "./privacy-keys.js";
 import { sanitizeTelemetry } from "./privacy-telemetry.js";
+import { errorField, safeErrorStack } from "./safe-error-fields.js";
 
 const DEFAULT_REDACT_FIELDS = [
   ...DEFAULT_SENSITIVE_KEYS
@@ -93,9 +94,6 @@ function sanitize(
   if (typeof value === "function" || typeof value === "symbol") {
     return `[${typeof value}]`;
   }
-  if (value instanceof Error) {
-    return sanitizeError(value, options, depth, visited);
-  }
   if (depth >= options.maxDepth) {
     return "[Truncated: depth]";
   }
@@ -104,6 +102,7 @@ function sanitize(
       return "[Circular]";
     }
     visited.add(value);
+    if (value instanceof Error) return sanitizeError(value, options, depth, visited);
     if (Array.isArray(value)) {
       return value
         .slice(0, options.maxArrayLength)
@@ -124,11 +123,13 @@ function sanitizeError(
   depth: number,
   visited: WeakSet<object>
 ): Record<string, unknown> {
+  const name = errorField(error, "name"), message = errorField(error, "message");
+  const stack = safeErrorStack(error), cause = Object.getOwnPropertyDescriptor(error, "cause");
   return {
-    name: truncate(error.name || "Error", options.maxStringLength, options.redactFields),
-    message: truncate(error.message || "", options.maxStringLength, options.redactFields),
-    stack: typeof error.stack === "string" ? truncate(error.stack, options.maxStringLength * 4, options.redactFields) : null,
-    cause: "cause" in error ? sanitize(error.cause, options, depth + 1, visited, "cause") : null
+    name: truncate(typeof name === "string" && name ? name : "Error", options.maxStringLength, options.redactFields),
+    message: truncate(typeof message === "string" ? message : "", options.maxStringLength, options.redactFields),
+    stack: typeof stack === "string" ? truncate(stack, options.maxStringLength * 4, options.redactFields) : null,
+    cause: cause && "value" in cause ? sanitize(cause.value, options, depth + 1, visited, "cause") : null
   };
 }
 

package/src/safe-error-fields.ts

@@ -0,0 +1,46 @@
+/** Read primitive native error fields without calling application accessors. */
+const nativePrototypes = new Set([Error.prototype, TypeError.prototype, RangeError.prototype, ReferenceError.prototype,
+  SyntaxError.prototype, URIError.prototype, EvalError.prototype, ...(typeof AggregateError === "function" ? [AggregateError.prototype] : [])]);
+const brandDescriptor = Object.getOwnPropertyDescriptor(Error, "isError");
+export const nativeBrand = brandDescriptor && "value" in brandDescriptor && typeof brandDescriptor.value === "function"
+  ? brandDescriptor.value as (value: unknown) => boolean : undefined;
+let nativeStackGetter: (() => unknown) | undefined;
+
+export function errorField(value: object, key: string): unknown {
+  const own = Object.getOwnPropertyDescriptor(value, key);
+  if (own) return "value" in own ? own.value : undefined;
+  let prototype = Object.getPrototypeOf(value);
+  for (let depth = 0; prototype && depth < 4; depth++) {
+    if (!nativePrototypes.has(prototype)) return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+    if (descriptor) return "value" in descriptor ? descriptor.value : undefined;
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return undefined;
+}
+export function safeErrorStack(value: object): unknown {
+  let prototype = Object.getPrototypeOf(value);
+  for (let depth = 0; prototype && depth < 4; depth++) {
+    if (!nativePrototypes.has(prototype) && prototype !== Object.prototype) return undefined;
+    for (const key of ["name", "message"]) {
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+      if (descriptor && (!("value" in descriptor) || typeof descriptor.value !== "string" || descriptor.value.length > 8192)) return undefined;
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  for (const key of ["name", "message"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor && (!("value" in descriptor) || typeof descriptor.value !== "string" || descriptor.value.length > 8192)) return undefined;
+  }
+  const formatter = Object.getOwnPropertyDescriptor(Error, "prepareStackTrace");
+  const limit = Object.getOwnPropertyDescriptor(Error, "stackTraceLimit");
+  if (formatter && (!("value" in formatter) || formatter.value !== undefined) ||
+    limit && (!("value" in limit) || typeof limit.value !== "number" || limit.value < 0 || limit.value > 64)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, "stack");
+  if (descriptor && "value" in descriptor) return descriptor.value;
+  if (descriptor?.get && nativeBrand?.(value)) {
+    nativeStackGetter ??= Object.getOwnPropertyDescriptor(new Error(), "stack")?.get;
+    if (descriptor.get === nativeStackGetter) return descriptor.get.call(value);
+  }
+  return undefined;
+}

package/src/types.ts

@@ -22,6 +22,9 @@ export interface DebugBundleConfig {
   maxEventsPerSession?: number;
   maxBreadcrumbs?: number;
   captureErrors?: boolean;
+  captureExceptionEvidence?: boolean;
+  captureRecoveryObservations?: boolean;
+  evidenceCapabilities?: EvidenceCapabilities;
   captureUnhandledRejections?: boolean;
   captureScreens?: boolean;
   captureActions?: boolean;
@@ -60,6 +63,9 @@ export interface ResolvedDebugBundleConfig {
   maxEventsPerSession: number;
   maxBreadcrumbs: number;
   captureErrors: boolean;
+  captureExceptionEvidence: boolean;
+  captureRecoveryObservations: boolean;
+  evidenceCapabilities: EvidenceCapabilities | null;
   captureUnhandledRejections: boolean;
   captureScreens: boolean;
   captureActions: boolean;
@@ -104,6 +110,8 @@ export interface DebugBundleResponseInfo {
 }
 
 export interface DebugBundleCaptureContext {
+  failureRef?: string;
+  evidenceScope?: EvidenceScope;
   [key: string]: unknown;
 }
 
@@ -112,26 +120,29 @@ export interface DebugBundleProbeOptions {
 }
 
 export interface DebugBundleEventEnvelope {
-  schema_version: "2026-03-01";
+  schema_version: string;
   event_id: string;
   event_type:
     | "frontend_exception"
+    | "backend_exception"
+    | "diagnostic_context"
+    | "deploy_metadata"
     | "frontend_breadcrumb"
     | "log_event"
     | "request_event"
     | "error_suppressed"
     | "probe_event";
-  sdk_name: "@debugbundle/sdk-react-native";
+  sdk_name: string;
   sdk_version: string;
   service: {
     name: string;
     environment: string;
-    runtime: "react-native";
-    framework: "react-native";
+    runtime?: string | null;
+    framework?: string | null;
   };
   occurred_at: string;
   correlation?: {
-    trace_id: string | null;
+    trace_id?: string | null;
     request_id?: string | null;
     session_id?: string | null;
     user_id_hash?: string | null;
@@ -143,6 +154,10 @@ export interface DebugBundleEventEnvelope {
 export interface DebugBundleClient {
   readonly status: DebugBundleStatus;
   readonly lastEventAt: number | null;
+  readonly evidenceCapabilities?: EvidenceCapabilities;
+  beginOperation?(): OperationScope;
+  withOperationContext?<T>(operation: (scope: OperationScope) => T): T;
+  captureRecovery?(observation: RecoveryObservation): void;
   init(config: DebugBundleConfig): void;
   captureException(error: unknown, context?: DebugBundleCaptureContext): void;
   captureError(error: unknown, context?: DebugBundleCaptureContext): void;
@@ -164,6 +179,7 @@ export interface DebugBundleClient {
 export interface NativeDebugBundleModule {
   initialize(config: NativeDebugBundleConfig): Promise<NativeDebugBundleState> | NativeDebugBundleState;
   enqueueCanonicalEvent?(event: DebugBundleEventEnvelope): Promise<boolean | void> | boolean | void;
+  enqueueCanonicalEventJson?(event: string): Promise<boolean | void> | boolean | void;
   /** Compatibility fallback implemented by native binaries released before the canonical bridge. */
   enqueueEvent(event: DebugBundleEventEnvelope): Promise<void> | void;
   captureProbe?(
@@ -185,6 +201,8 @@ export interface NativeDebugBundleState {
   status: DebugBundleStatus;
   lastEventAt?: number | null;
   device?: Record<string, unknown> | null;
+  evidenceCapabilities?: unknown;
   nativeModuleAvailable?: boolean;
   degradedReason?: string | null;
 }
+import type { EvidenceCapabilities, EvidenceScope, OperationScope, RecoveryObservation } from "./evidence-types.js";