@hanzo/event 0.3.48 → 0.3.49

package/src/core.ts

@@ -7,21 +7,10 @@
 //      Cloud resolves the tenant server-side (validated session, or the signed
 //      publishable key) and stamps it; the client NEVER sends the org.
 //
-//   2. ERROR PLANE — every captured exception is ALSO framed as a real Sentry
-//      envelope and POSTed to the error host named by the DSN:
-//        POST {dsn.base}/envelope/?sentry_key=…   ({base} = /v1/event/{projectId})
-//      This is what reaches sentry.hanzo.ai (issues, grouping, stack frames).
-//
-// These are NOT the same pipe and one does NOT feed the other. The event stream
-// stores a `type:'error'` row in the cloud event warehouse (readable via
-// GET /v1/errors) — that is product signal, not error tracking. There is no
-// server-side fan-out from /v1/event into Sentry; without the envelope below,
-// nothing ever reaches sentry.hanzo.ai. An earlier revision of this file claimed
-// the one entry point was "lensed server-side into … error tracking (sentry)". It was
-// wrong, and it silently cost the fleet all of its error telemetry.
-//
-// The error plane is inert (fail-safe) when no DSN is configured: nothing is
-// sent, nothing throws, and the event stream is unaffected.
+//   Errors ride the same pipe: a captured exception is ONE event of type 'error'
+//   carrying {type, message, frames|stack, handled} plus release, environment,
+//   site, product and level. The server files it on the error plane and groups it
+//   into an issue. There is no second endpoint, DSN or envelope.
 //
 // Auth is orthogonal — the SAME body to the SAME endpoint, differing only in how the
 // caller proves its tenant:
@@ -34,29 +23,17 @@
 //     is the carrier neither send needs a header for, which is what keeps both
 //     CORS-simple and therefore sendable from a customer's own origin.
 //
-// The wire is the canonical `Event` (== the cloud CaptureEvent): its `type` field
-// is what Cloud folds to event_type='error', which is how the event WAREHOUSE
-// classifies the row (GET /v1/errors). That is the extent of it — the fold does
-// not forward anything to Sentry. The error dashboard is fed only by the envelope
-// in plane 2 above, and only when a DSN is set.
+// The wire is the canonical `Event` (== the cloud CaptureEvent).
 
 import {
   parseAttribution,
   hasAttribution,
   deriveChannel,
 } from './attribution'
-import { dsnForProduct } from './dsn'
 import { keyForPage } from './org'
-import { EXCEPTION, PAGEVIEW } from './events'
-import { exceptionProperties } from './exception'
+import { PAGEVIEW } from './events'
 import { scrubText, withoutFragment } from './scrub'
-import {
-  buildEnvelope,
-  buildSentryEvent,
-  normalizeError as normalizeThrowable,
-  parseDsn,
-  type ErrorIdentity,
-} from './sentry'
+import { framesFromStack, normalizeError as normalizeThrowable } from './throwable'
 import {
   adoptAnonId,
   adoptSession,
@@ -74,7 +51,6 @@ import type {
   Attribution,
   CaptureErrorOptions,
   Cohort,
-  Dsn,
   EventKind,
   Exception,
   Transport,
@@ -86,7 +62,6 @@ export { VERSION }
 
 const EVENT_PATH = '/v1/event' // the ONE canonical ingestion entry point
 const DEFAULT_HOST = 'https://api.hanzo.ai' // the one edge; cookie apps pass host:''
-const ENVELOPE_CONTENT_TYPE = 'application/x-sentry-envelope'
 // The beacon body's type. text/plain is CORS-SAFELISTED, which is the whole
 // property: a safelisted type makes the POST a SIMPLE request, and a simple
 // request needs no preflight. An unloading document does not get a second round
@@ -95,22 +70,7 @@ const ENVELOPE_CONTENT_TYPE = 'application/x-sentry-envelope'
 // CORS class and nothing else.
 const BEACON_CONTENT_TYPE = 'text/plain'
 
-/** readEnvDsn resolves a DSN from the public env when config omits one, so an app
- *  gets the error plane by setting ONE build-time variable and nothing else.
- *  Next/Vite inline these at build; the access is guarded so it is safe in a bare
- *  browser and during SSR/prerender where `process` may not exist. */
-function readEnvDsn(): string | undefined {
-  try {
-    if (typeof process !== 'undefined' && process.env) {
-      return process.env.NEXT_PUBLIC_HANZO_EVENT_DSN || process.env.HANZO_EVENT_DSN || undefined
-    }
-  } catch {
-    /* no process — browser without inlined env */
-  }
-  return undefined
-}
-
-/** readEnv reads an inlined build-time variable, guarded like readEnvDsn. */
+/** readEnv reads an inlined build-time variable, guarded for SSR. */
 function readEnv(name: string): string | undefined {
   try {
     if (typeof process !== 'undefined' && process.env) return process.env[name] || undefined
@@ -127,14 +87,15 @@ function appendQuery(url: string, key: string, value: string): string {
 }
 
 /** Normalize anything thrown (Error | string | unknown) into an Exception. */
-/** normalizeError adapts the shared, hostile-input-safe normalizer (sentry.ts) to
- *  the event stream's Exception shape. ONE normalizer serves both planes: a thrown
- *  object may define `name`/`message`/`stack` as throwing getters, and when each
- *  plane rolled its own reader the stream still lost the report that the error
- *  plane had already survived. */
+/** normalizeError adapts the hostile-input-safe normalizer (sentry.ts) to the
+ *  stream's Exception shape: a thrown object may define `name`/`message`/`stack`
+ *  as throwing getters. */
 function normalizeError(err: unknown): Exception {
   const n = normalizeThrowable(err)
-  return { type: n.name, message: n.message, stack: n.stack }
+  const frames = framesFromStack(n.stack)
+    .slice(-50)
+    .map((f) => ({ function: f.function, file: f.filename, line: f.lineno, column: f.colno }))
+  return { type: n.name, message: n.message, stack: n.stack, frames }
 }
 
 // React Native defines a `window` but no `document` (and no `window.location`),
@@ -267,8 +228,6 @@ export class Analytics {
   private started = false
   /** The view pageview() last counted — path + location. */
   private counted?: string
-  /** Parsed error-plane DSN, or null when the plane is inert. */
-  private dsn: Dsn | null
   /** Guards against an error thrown *inside* the error path re-entering it. */
   private reentrant = false
 
@@ -304,43 +263,14 @@ export class Analytics {
         config.ingestKey ?? readEnv('NEXT_PUBLIC_PUBLISHABLE_KEY') ?? keyForPage(),
     }
     this.transport = config.transport ?? new DefaultTransport()
-    // Error plane, most specific source first: an explicit DSN wins, then the
-    // inlined build-time env (a per-deploy override), then the product registry —
-    // whose DSN carries the SAME resolved key (not a baked one), so declaring
-    // `product` + providing the key is enough to report errors. Malformed or
-    // absent => null => inert, never throwing into the host app.
-    this.dsn = parseDsn(
-      config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product, this.cfg.ingestKey)
-    )
   }
 
   /** adopt gives this client a credential it does not have. The key belongs to
    *  the stream, not to whichever caller happened to ask for the handle first,
-   *  so a later caller carrying one hands it over. The error plane derives from
-   *  the key, so it comes up here too when it was inert for want of one.
-   *  Present fields are never overwritten: the first caller's key stays. */
+   *  so a later caller carrying one hands it over. Present fields are never overwritten: the first caller's key stays. */
   adopt(config: AnalyticsConfig): void {
     if (config.ingestKey && !this.cfg.ingestKey) this.cfg.ingestKey = config.ingestKey
     if (config.getToken && !this.cfg.getToken) this.cfg.getToken = config.getToken
-    if (!this.dsn) {
-      this.dsn = parseDsn(
-        config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product, this.cfg.ingestKey),
-      )
-    }
-  }
-
-  /** errorPlaneEnabled reports whether captured exceptions can actually reach the
-   *  error host. False means a DSN was never configured — the documented
-   *  fail-safe. Exposed so an app (or a test) can assert its wiring instead of
-   *  discovering months later that nothing was ever reported. */
-  get errorPlaneEnabled(): boolean {
-    return this.dsn !== null
-  }
-
-  /** errorIngestUrl is the fully-derived envelope endpoint, or undefined when the
-   *  plane is inert. Diagnostics only. */
-  get errorIngestUrl(): string | undefined {
-    return this.dsn?.ingestUrl
   }
 
   /** init is idempotent and browser-only for its side effects: capture first-touch
@@ -383,10 +313,7 @@ export class Analytics {
     window.addEventListener('visibilitychange', flushHidden)
     window.addEventListener('pagehide', () => this.flush(true))
 
-    // Auto error capture — the drop-in @sentry replacement. Unhandled errors and
-    // rejected promises are reported on BOTH planes: a Sentry envelope to the DSN
-    // host (what reaches the error dashboard — requires a DSN) and a type:'error'
-    // event on the stream (product signal in the warehouse).
+    // Unhandled errors and rejected promises are reported as type:'error' events.
     if (this.cfg.captureErrors) {
       window.addEventListener('error', (e: ErrorEvent) => {
         this.captureError(e.error ?? e.message, { handled: false })
@@ -462,71 +389,30 @@ export class Analytics {
   }
 
   /** captureError reports a caught error, an unhandled rejection, a React render
-   *  error, or a manual report to BOTH planes, from one call:
-   *
-   *    - the ERROR PLANE — a real Sentry envelope to the DSN host. This is the one
-   *      that produces an issue in sentry.hanzo.ai (grouping, stack frames, AST).
-   *      Inert when no DSN is configured.
-   *    - the EVENT STREAM — a `type:'error'` row in the cloud event warehouse, so
-   *      an error stays correlated with the session's pageviews for product
-   *      analysis (readable via GET /v1/errors).
-   *
-   *  Both carry the SAME session and subject id, so an error and the pageview
-   *  before it join up. Never throws back into the app; errors are higher-signal
-   *  than pageviews, so both planes flush promptly (a crash may unload the page
-   *  moments later). */
+   *  error, or a manual report as ONE event of type 'error' on the one stream.
+   *  It carries the exception (type, message, frames, stack, handled) and the
+   *  release, environment, site, product and level that group and scope it, and
+   *  flushes promptly (a crash may unload the page moments later). Never throws
+   *  back into the app. */
   captureError(err: unknown, context?: CaptureErrorOptions): void {
     // A failure inside the error path must not recurse through the global handlers.
     if (this.reentrant) return
     this.reentrant = true
     try {
-      // ERROR PLANE FIRST, in its own try. The planes are independent, so neither
-      // may be able to starve the other: `properties` is arbitrary caller data
-      // (a DOM node, a React synthetic event, an axios error — all circular and
-      // all common), and serializing it on the event stream can throw. When the
-      // stream ran first, that throw escaped to the outer catch and the crash
-      // report was never sent — silently losing exactly the signal this client
-      // exists to deliver. Order and isolation are the fix.
-      try {
-        this.sendError(err, context)
-      } catch {
-        /* the error plane must never take the event stream down with it */
-      }
-
-      try {
-        const handled = context?.handled ?? true
-        const ex = normalizeError(err)
-        ex.handled = handled
-        // NAME: the reserved '$exception', never the message. The message was the
-        // name until 0.3.20, which put every distinct error string — one per failed
-        // chunk id, per ResizeObserver notification — permanently into the event
-        // taxonomy, and left Error Tracking (which reads this exact name) at zero.
-        //
-        // TYPE 'event', not 'error'. `type` alone picks the storage plane: 'error'
-        // routes to the error plane, which the product-event projection does not
-        // read, so an exception filed there is invisible to Error Tracking however
-        // well-formed it is. The full error record still reaches the error plane as
-        // a Sentry envelope above — this row is the product-analytics breadcrumb,
-        // which is what keeps a crash correlated with the session's pageviews.
-        //
-        // `error` is still carried: the server folds it into properties.$exception
-        // (scrubbing message and stack on the way), which is the shape existing
-        // readers bind to.
-        this.enqueue('event', EXCEPTION, {
-          error: ex,
-          properties: {
-            ...context?.properties,
-            ...exceptionProperties(err, {
-              handled,
-              id: uuidv7(),
-              level: context?.level,
-            }),
-          },
-        })
-        this.flush()
-      } catch {
-        /* nor the reverse */
-      }
+      const handled = context?.handled ?? true
+      const ex = normalizeError(err)
+      ex.handled = handled
+      this.enqueue('error', undefined, {
+        error: ex,
+        level: context?.level ?? (handled ? 'error' : 'fatal'),
+        release: this.cfg.release ?? readEnv('NEXT_PUBLIC_HANZO_RELEASE'),
+        environment: this.cfg.environment ?? readEnv('NODE_ENV'),
+        site: isBrowser() ? window.location.hostname : undefined,
+        properties: context?.properties,
+      })
+      this.flush()
+    } catch {
+      /* the error path never takes the app down */
     } finally {
       this.reentrant = false
     }
@@ -588,41 +474,6 @@ export class Analytics {
 
   // ── internals ────────────────────────────────────────────────────────────
 
-  /** sendError frames one exception as a Sentry envelope and posts it to the DSN's
-   *  ingest URL. The DSN's own key rides ?sentry_key= (the credential channel the
-   *  server trusts, and the only one a headerless beacon can carry), so NO bearer
-   *  or publishable key is attached here — the two planes authenticate
-   *  independently. Errors are sent one envelope per event, immediately: batching
-   *  a crash report is how you lose it. */
-  private sendError(err: unknown, options?: CaptureErrorOptions): void {
-    if (!this.cfg.enabled || !this.dsn) return
-    const event = buildSentryEvent({
-      error: err,
-      options,
-      identity: this.errorIdentity(),
-      capturePII: this.cfg.capturePII ?? false,
-    })
-    const body = buildEnvelope(event, this.dsn)
-    if (this.cfg.debug) console.debug('[event] error →', this.dsn.ingestUrl, event.event_id)
-    this.transport.send(this.dsn.ingestUrl, body, {
-      beacon: false,
-      contentType: ENVELOPE_CONTENT_TYPE,
-      debug: this.cfg.debug,
-    })
-  }
-
-  /** errorIdentity is the SAME identity the event stream stamps — the OIDC subject
-   *  once identify() has run, else the anon id. Never email/PII. */
-  private errorIdentity(): ErrorIdentity {
-    return {
-      userId: this.personId ?? anonId(),
-      sessionId: sessionId(),
-      product: this.cfg.product,
-      release: this.cfg.release ?? readEnv('NEXT_PUBLIC_HANZO_RELEASE'),
-      environment: this.cfg.environment ?? readEnv('NODE_ENV'),
-    }
-  }
-
   private enqueue(kind: EventKind, event: string | undefined, extra: Partial<WireEvent>): void {
     if (!this.cfg.enabled) return
     if (!this.started) this.init()

package/src/exception.ts

@@ -29,7 +29,7 @@
 // throw site. framesFromStack (sentry.ts) already returns that order, which is why
 // this module reuses it rather than re-parsing.
 
-import { framesFromStack, normalizeError } from './sentry'
+import { framesFromStack, normalizeError } from './throwable'
 import type {
   ExceptionEntry,
   ExceptionFrame,

package/src/index.ts

@@ -15,12 +15,10 @@ export {
   getCohort,
   getFirstTouch,
 } from './core'
-export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
+export { framesFromStack } from './throwable'
 export { uuidv7, uuidv7Time } from './uid'
 export { linkUrl, readLink, stripLink, LINK_PARAMS } from './link'
 export type { LinkState } from './link'
-export { PRODUCT_PROJECT, dsnForProduct } from './dsn'
-export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'
 export { EVENTS, EXCEPTION, PAGEVIEW } from './events'
 export { exceptionEntry, exceptionProperties, fingerprint, digest } from './exception'
@@ -51,13 +49,11 @@ export type {
   Attribution,
   CaptureErrorOptions,
   Cohort,
-  Dsn,
   EventKind,
   Exception,
   ExceptionEntry,
   ExceptionFrame,
   ExceptionProperties,
-  SentryEvent,
   SentryFrame,
   SentryLevel,
   Transport,

package/src/org.ts

@@ -51,11 +51,15 @@ export const ORG_DOMAIN: Readonly<Record<string, readonly string[]>> = Object.fr
   // separate fact, which is the whole reason this is a table.
   hanzo: Object.freeze([
     'hanzo.ai',
+    'hanzo.agency',
     'hanzo.app',
     'hanzo.bot',
     'hanzo.chat',
     'hanzo.codes',
     'hanzo.id',
+    'hanzo.industries',
+    'hanzo.market',
+    'hanzo.network',
     'hanzo.sh',
     'hanzo.team',
     'hanzo.ventures',

package/src/stream.test.ts

@@ -81,13 +81,6 @@ describe('one stream, one client', () => {
     expect(tx.sent[0].token).toBe(KEY)
   })
 
-  it('brings up the error plane on the key it adopts', () => {
-    const a = createAnalytics({ product: 'console', host: HOST, transport: tx })
-    expect(a.errorPlaneEnabled).toBe(false)
-    createAnalytics({ product: 'console', host: HOST, ingestKey: KEY })
-    expect(a.errorPlaneEnabled).toBe(true)
-  })
-
   it('keeps the first credential rather than overwriting it', () => {
     createAnalytics({ product: 'site', host: HOST, ingestKey: KEY, transport: tx })
     createAnalytics({ product: 'site', host: HOST, ingestKey: 'pk-second' }).capture('x')

package/src/throwable.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+import { framesFromStack, normalizeError } from './throwable'
+
+describe('framesFromStack', () => {
+  it('parses a V8 stack oldest-first with in_app marking', () => {
+    const stack = [
+      'TypeError: x is not a function',
+      '    at inner (https://app.hanzo.ai/app.js:10:5)',
+      '    at outer (https://app.hanzo.ai/app.js:20:1)',
+      '    at eval (webpack-internal:///./node_modules/lib/index.js:3:2)',
+    ].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(3)
+    // oldest-first: the node_modules frame is the outermost caller (first),
+    // the crash site (inner) is last.
+    expect(frames[frames.length - 1].function).toBe('inner')
+    expect(frames[frames.length - 1].lineno).toBe(10)
+    expect(frames[frames.length - 1].in_app).toBe(true)
+    expect(frames[0].function).toBe('eval')
+    expect(frames[0].in_app).toBe(false) // node_modules
+  })
+  it('parses a Firefox/Safari stack (fn@file:li:co and bare @file)', () => {
+    const stack = ['boom@https://app.hanzo.ai/a.js:1:2', '@https://app.hanzo.ai/b.js:3:4'].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(2)
+    expect(frames[frames.length - 1].function).toBe('boom')
+    expect(frames[frames.length - 1].filename).toBe('https://app.hanzo.ai/a.js')
+  })
+  it('skips the header line and tolerates junk', () => {
+    expect(framesFromStack('Error: nope\n   total garbage line')).toHaveLength(0)
+    expect(framesFromStack(undefined)).toHaveLength(0)
+  })
+})
+
+describe('normalizeError', () => {
+  it('coerces Error, string, and objects', () => {
+    expect(normalizeError(new RangeError('r')).name).toBe('RangeError')
+    expect(normalizeError('boom')).toEqual({ name: 'Error', message: 'boom' })
+    expect(normalizeError({ a: 1 }).message).toBe('{"a":1}')
+  })
+})
+
+describe('normalizeError survives hostile input', () => {
+  const bomb = (prop: string) => {
+    const e = new Error('real message')
+    Object.defineProperty(e, prop, {
+      get() {
+        throw new Error(prop + ' bomb')
+      },
+      configurable: true,
+    })
+    return e
+  }
+
+  for (const prop of ['stack', 'message', 'name']) {
+    it(`a throwing ${prop} getter does not throw`, () => {
+      expect(() => normalizeError(bomb(prop))).not.toThrow()
+      const n = normalizeError(bomb(prop))
+      expect(typeof n.name).toBe('string')
+      expect(typeof n.message).toBe('string')
+    })
+  }
+
+  it('an object with a throwing toString is still reportable', () => {
+    const evil = {
+      toString() {
+        throw new Error('toString bomb')
+      },
+    }
+    expect(() => normalizeError(evil)).not.toThrow()
+  })
+})

package/src/throwable.ts

@@ -0,0 +1,126 @@
+// Pure throwable parsing: coerce anything thrown into {name, message, stack} and
+// parse a browser stack into frames. No I/O, no globals.
+
+import type { SentryFrame } from './types'
+
+const MAX_FRAMES = 50
+/** Max stack lines examined, and max length of a line worth examining. Guards the
+ *  frame regexes against a hostile `stack` string (see framesFromStack). */
+const MAX_LINES = 500
+const MAX_LINE_LEN = 2048
+
+const V8_FRAME = /^\s*at\s+(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+)|([^)]+))\)?\s*$/
+const MOZ_FRAME = /^\s*(?:(.*?)@)?(.+?):(\d+):(\d+)\s*$/
+
+/** inApp marks a frame as the app's own code (vs vendor/runtime) for grouping. */
+function inApp(file: string): boolean {
+  if (!file) return false
+  return !(
+    file.includes('node_modules') ||
+    file.startsWith('webpack-internal') ||
+    file.startsWith('webpack://') ||
+    file.startsWith('chrome-extension://') ||
+    file.startsWith('moz-extension://')
+  )
+}
+
+/**
+ * framesFromStack parses a browser Error.stack into Sentry frames, OLDEST-FIRST
+ * (Sentry orders caller->callee; the crash site is last — matching the server's
+ * pickCrashFrame). Handles both V8 ("at fn (file:li:co)") and
+ * Firefox/Safari ("fn@file:li:co"). Unparseable lines are skipped.
+ */
+export function framesFromStack(stack: string | undefined): SentryFrame[] {
+  if (!stack) return []
+  // Both frame regexes use lazy nested quantifiers, which backtrack badly on a
+  // long line that never matches. A stack is attacker-influenced (a thrown value
+  // can carry any `stack` string), so bound the work: skip absurd lines and stop
+  // after MAX_LINES. Only the innermost MAX_FRAMES are kept anyway.
+  const lines = stack.split('\n', MAX_LINES)
+  const frames: SentryFrame[] = []
+  for (const raw of lines) {
+    if (raw.length > MAX_LINE_LEN) continue
+    const line = raw.trimEnd()
+    if (!line) continue
+    // Header lines like "TypeError: x is not a function" match neither frame
+    // regex (no "at " prefix, no trailing :line:col) and are skipped naturally.
+    let fn: string | undefined
+    let file = ''
+    let lineno = 0
+    let colno = 0
+    const v = V8_FRAME.exec(line)
+    if (v) {
+      fn = v[1]
+      if (v[2]) {
+        file = v[2]
+        lineno = Number(v[3]) || 0
+        colno = Number(v[4]) || 0
+      } else {
+        file = (v[5] || '').trim()
+      }
+    } else {
+      const f = MOZ_FRAME.exec(line)
+      if (!f) continue
+      fn = f[1]
+      file = f[2]
+      lineno = Number(f[3]) || 0
+      colno = Number(f[4]) || 0
+    }
+    if (!file && !fn) continue
+    frames.push({
+      function: fn || '<anonymous>',
+      filename: file,
+      abs_path: file,
+      lineno,
+      colno,
+      in_app: inApp(file),
+    })
+  }
+  // Reverse to oldest-first and cap to the innermost MAX_FRAMES.
+  frames.reverse()
+  if (frames.length > MAX_FRAMES) return frames.slice(frames.length - MAX_FRAMES)
+  return frames
+}
+
+/** normalizeError coerces an unknown throwable into {name, message, stack}. */
+export function normalizeError(err: unknown): { name: string; message: string; stack?: string } {
+  if (err instanceof Error) {
+    // `name`, `message` and `stack` are ordinary getters, and the thrown object is
+    // the least trustworthy input this library handles — any of them may throw.
+    // Losing the whole report to a hostile getter is not acceptable.
+    const name = read(err, 'name')
+    const message = read(err, 'message')
+    const stack = read(err, 'stack')
+    return {
+      name: typeof name === 'string' && name ? name : 'Error',
+      message: typeof message === 'string' && message ? message : str(err),
+      stack: typeof stack === 'string' ? stack : undefined,
+    }
+  }
+  if (typeof err === 'string') return { name: 'Error', message: err }
+  try {
+    return { name: 'Error', message: JSON.stringify(err) ?? str(err) }
+  } catch {
+    return { name: 'Error', message: str(err) }
+  }
+}
+
+/** read pulls a property off a possibly-hostile value without letting a throwing
+ *  getter escape. */
+function read(o: unknown, k: string): unknown {
+  try {
+    return (o as Record<string, unknown>)[k]
+  } catch {
+    return undefined
+  }
+}
+
+/** str coerces to a string without letting a throwing toString/Symbol.toPrimitive
+ *  escape. */
+function str(v: unknown): string {
+  try {
+    return String(v)
+  } catch {
+    return '[unstringifiable]'
+  }
+}