@hanzo/event 0.3.19 → 0.3.21

package/src/core.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest'
 import { Analytics, VERSION } from './core'
-import { HANZO_PUBLISHABLE_KEY } from './dsn'
 import { EVENTS, PAGEVIEW } from './events'
 import type { Transport, WireEvent } from './types'
 import pkg from '../package.json' with { type: 'json' }
@@ -384,48 +383,15 @@ describe('Analytics capture', () => {
     }
   })
 
-  it('stays keyless when neither config nor env names a key, off the hanzo cloud', () => {
-    // mk() uses host:'' — a same-origin app, deliberately NOT defaulted.
-    const a = mk()
-    a.capture('x')
-    a.flush(true)
-    expect(tx.sent[0].ingestKey).toBeUndefined()
-  })
-
-  it('bakes the hanzo publishable key as the default ON the hanzo cloud', () => {
-    // publishable_key for all: a hanzo surface that passes no key and inlines no
-    // env still emits attributed, the same way declaring `product` is enough for
-    // the DSN. No wiring, no $public, no silent drop of track/identify/group.
+  it('stays keyless when neither config nor env names a key — no baked literal', () => {
+    // The key comes from ONE live source (config or the KMS-sourced env); nothing
+    // is hardcoded, so a surface that provides neither is honestly keyless.
     const a = mk({ host: 'https://api.hanzo.ai' })
     a.capture('x')
     a.flush(true)
-    expect(tx.sent[0].ingestKey).toBe(HANZO_PUBLISHABLE_KEY)
-  })
-
-  it('does NOT bake the default for a white-label (non-hanzo) host', () => {
-    const a = mk({ host: 'https://api.zoo.ngo' })
-    a.capture('x')
-    a.flush(true)
     expect(tx.sent[0].ingestKey).toBeUndefined()
   })
 
-  it('lets an explicit key and the build env each override the baked default', () => {
-    const explicit = mk({ host: 'https://api.hanzo.ai', ingestKey: 'pk-explicit' })
-    explicit.capture('x')
-    explicit.flush(true)
-    expect(tx.sent[0].ingestKey).toBe('pk-explicit')
-
-    process.env.NEXT_PUBLIC_PUBLISHABLE_KEY = 'pk-from-env'
-    try {
-      const env = mk({ host: 'https://api.hanzo.ai' }) // mk() reassigns `tx`
-      env.capture('y')
-      env.flush(true)
-      expect(tx.sent[0].ingestKey).toBe('pk-from-env')
-    } finally {
-      delete process.env.NEXT_PUBLIC_PUBLISHABLE_KEY
-    }
-  })
-
   it('a signed-in bearer WINS over a key from the build env', () => {
     // The leak this closes: one console bundle is served to several brands, and a
     // pk- names ONE org. If an env-sourced key displaced the bearer, every
@@ -483,45 +449,78 @@ describe('Analytics capture', () => {
 })
 
 describe('Event error capture', () => {
-  it('captureError emits a type:error event carrying a TOP-LEVEL exception, flushed at once', () => {
+  it('emits under the RESERVED $exception name, never under the message', () => {
     const a = mk()
     a.captureError(new TypeError('boom'))
     // captureError flushes promptly — no explicit flush() needed.
     expect(tx.sent).toHaveLength(1)
     const e = tx.all[0]
-    // type:'error' is the field Cloud folds to event_type='error' for the warehouse.
-    expect(e.type).toBe('error')
-    expect(e.event).toBe('boom')
-    // The exception rides the TOP-LEVEL `error` field (what cloud foldException
-    // reads), NOT properties — a properties-only exception would not be folded.
+    // THE NAME. Until 0.3.20 this was `ex.message`, which made every distinct
+    // error string a permanent entry in the event taxonomy and left Error
+    // Tracking — which reads this exact name — at zero rows.
+    expect(e.event).toBe('$exception')
+    // THE TYPE. `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 cannot reach Error Tracking. The full error record still goes to
+    // the error plane as a Sentry envelope.
+    expect(e.type).toBe('event')
+    // The exception STILL rides the TOP-LEVEL `error` field, which is what cloud's
+    // foldException reads to stamp properties.$exception (scrubbing on the way).
     expect(e.error?.type).toBe('TypeError')
     expect(e.error?.message).toBe('boom')
     expect(e.error?.stack).toBeTruthy()
     expect(e.error?.handled).toBe(true) // a caught, manually-reported error
-    expect((e.properties ?? {})).not.toHaveProperty('$exception')
+    // The client does not stamp $exception itself — the server fold owns that key.
+    expect(e.properties ?? {}).not.toHaveProperty('$exception')
+  })
+
+  it('carries the $exception_* bag Error Tracking reads', () => {
+    const a = mk()
+    a.captureError(new TypeError('boom'))
+    const p = tx.all[0].properties as Record<string, unknown>
+    expect(Array.isArray(p.$exception_list)).toBe(true)
+    // Without a fingerprint the issue query drops the event outright.
+    expect(p.$exception_fingerprint).toMatch(/^[0-9a-f]{32}$/)
+    expect(p.$exception_type).toBe('TypeError')
+    expect(p.$exception_handled).toBe(true)
   })
 
   it('normalizes a thrown string into an exception', () => {
     const a = mk()
     a.captureError('plain failure')
     const e = tx.all[0]
-    expect(e.type).toBe('error')
+    expect(e.event).toBe('$exception')
+    expect(e.type).toBe('event')
     expect(e.error?.message).toBe('plain failure')
   })
 
-  it('marks handled=false for unhandled/global errors and carries properties', () => {
+  it('marks handled=false for unhandled/global errors and carries caller properties', () => {
     const a = mk()
     a.captureError(new Error('unhandled'), { handled: false, properties: { source: 'onerror' } })
     const e = tx.all[0]
     expect(e.error?.handled).toBe(false)
-    expect(e.properties).toEqual({ source: 'onerror' })
+    const p = e.properties as Record<string, unknown>
+    // The caller's own properties survive alongside the exception bag.
+    expect(p.source).toBe('onerror')
+    expect(p.$exception_handled).toBe(false)
+  })
+
+  it("a caller property cannot overwrite the exception bag it shares a name with", () => {
+    const a = mk()
+    a.captureError(new Error('x'), {
+      handled: false,
+      properties: { $exception_fingerprint: 'forged' },
+    })
+    const p = tx.all[0].properties as Record<string, unknown>
+    expect(p.$exception_fingerprint).not.toBe('forged')
   })
 
   it('captureException is an alias of captureError', () => {
     const a = mk()
     a.captureException(new Error('via alias'))
     const e = tx.all[0]
-    expect(e.type).toBe('error')
+    expect(e.event).toBe('$exception')
+    expect(e.type).toBe('event')
     expect(e.error?.message).toBe('via alias')
   })
 
@@ -563,7 +562,7 @@ describe('error plane', () => {
     expect(tx.envelopes).toHaveLength(0)
     // fail-safe: the event stream still carries the error, analytics untouched.
     expect(tx.streams).toHaveLength(1)
-    expect(tx.all[0].type).toBe('error')
+    expect(tx.all[0].event).toBe('$exception')
   })
 
   it('with a DSN, an error POSTs a Sentry envelope to the DERIVED ingest URL', () => {

package/src/core.ts

@@ -43,8 +43,9 @@ import {
   hasAttribution,
   deriveChannel,
 } from './attribution'
-import { dsnForProduct, defaultPublishableKey } from './dsn'
-import { PAGEVIEW } from './events'
+import { dsnForProduct } from './dsn'
+import { EXCEPTION, PAGEVIEW } from './events'
+import { exceptionProperties } from './exception'
 import { scrubText } from './scrub'
 import {
   buildEnvelope,
@@ -238,35 +239,29 @@ export class Analytics {
       enabled: true,
       captureErrors: true,
       ...config,
-      // The publishable key resolves the SAME way the DSN below does, and now
-      // ends the SAME way too — in a baked default, so declaring nothing is
-      // enough. Most specific first:
+      // The publishable key resolves from ONE live source, never a literal baked
+      // beside the code. Most specific first:
       //   1. an explicit `ingestKey` in config;
       //   2. NEXT_PUBLIC_PUBLISHABLE_KEY, the inlined build-time env the fleet
-      //      carries end to end (KMS `deploy/PUBLISHABLE_KEY` -> the PUBLISHABLE_KEY
-      //      build-arg -> the NEXT_PUBLIC_ prefix Next inlines);
-      //   3. the hanzo org key baked in `dsn.ts`, on the hanzo cloud only.
+      //      carries end to end — KMS `deploy/PUBLISHABLE_KEY` -> the PUBLISHABLE_KEY
+      //      build-arg -> the NEXT_PUBLIC_ prefix Next inlines.
       //
-      // (3) is why this is `publishable_key for all`: a hanzo surface that passes
-      // no key in code and inlines no env still emits attributed, exactly as
-      // declaring `product` is enough for the DSN. Without it that surface sent
-      // its beacons to `$public` — which drops every track/identify/group and
-      // still answers 200 — silent in the page and invisible until you read the
-      // warehouse and find the host missing entirely. A white-label surface on
-      // its own cloud (a non-default host) gets no default, so the org this
-      // attributes to is never the wrong one.
-      ingestKey:
-        config.ingestKey ??
-        readEnv('NEXT_PUBLIC_PUBLISHABLE_KEY') ??
-        defaultPublishableKey(config.host ?? DEFAULT_HOST),
+      // A surface that provides neither has no key, and its anonymous traffic
+      // files under `$public` (which drops track/identify/group and answers 200);
+      // the fix is to give it the KMS-sourced env, not to hardcode the org key
+      // here. The key is a credential-class value: its home is KMS, and the ONE
+      // build reads it from there.
+      ingestKey: config.ingestKey ?? readEnv('NEXT_PUBLIC_PUBLISHABLE_KEY'),
     }
     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
-    // — so declaring `product` is enough to report errors and no surface needs
-    // build-argument plumbing. Malformed or absent => null => inert, never
-    // throwing into the host app.
-    this.dsn = parseDsn(config.dsn ?? readEnvDsn() ?? dsnForProduct(this.cfg.product))
+    // 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)
+    )
   }
 
   /** errorPlaneEnabled reports whether captured exceptions can actually reach the
@@ -389,9 +384,35 @@ export class Analytics {
       }
 
       try {
+        const handled = context?.handled ?? true
         const ex = normalizeError(err)
-        ex.handled = context?.handled ?? true
-        this.enqueue('error', ex.message, { error: ex, properties: context?.properties })
+        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 */

package/src/dsn.test.ts

@@ -1,64 +1,74 @@
 import { describe, it, expect, afterEach } from 'vitest'
 
 import { createAnalytics } from './core'
-import { PRODUCT_PROJECT, dsnForProduct, HANZO_PUBLISHABLE_KEY } from './dsn'
+import { PRODUCT_PROJECT, dsnForProduct } from './dsn'
 import { parseDsn } from './sentry'
 
 const ENV = 'NEXT_PUBLIC_HANZO_EVENT_DSN'
 const OVERRIDE = 'https://1:aaaa@api.hanzo.ai/v1/sentry/env-project'
 const EXPLICIT = 'https://1:bbbb@api.hanzo.ai/v1/sentry/explicit-project'
+// A stand-in for the surface's own resolved key — the DSN carries whatever key
+// the caller resolved (config or the KMS-sourced env), never a literal.
+const KEY = 'pk-test-resolved-key'
 
 afterEach(() => {
   delete process.env[ENV]
 })
 
 describe('the product registry', () => {
-  it('builds a product DSN — the org publishable key at its project envelope', () => {
-    expect(dsnForProduct('console')).toBe(
-      `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.console}`
+  it('builds a product DSN from the CALLER key + the project — nothing baked', () => {
+    expect(dsnForProduct('console', KEY)).toBe(
+      `https://${KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.console}`
     )
-    expect(dsnForProduct('site')).toBe(
-      `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.site}`
+    expect(dsnForProduct('site', KEY)).toBe(
+      `https://${KEY}@api.hanzo.ai/v1/sentry/${PRODUCT_PROJECT.site}`
     )
   })
 
-  it('returns undefined for an unregistered or missing product, rather than guessing', () => {
-    expect(dsnForProduct('not-a-product')).toBeUndefined()
-    expect(dsnForProduct(undefined)).toBeUndefined()
-    expect(dsnForProduct('')).toBeUndefined()
+  it('returns undefined without a key or without a project, rather than guessing', () => {
+    expect(dsnForProduct('console', undefined)).toBeUndefined() // no key -> inert
+    expect(dsnForProduct('not-a-product', KEY)).toBeUndefined()
+    expect(dsnForProduct(undefined, KEY)).toBeUndefined()
+    expect(dsnForProduct('', KEY)).toBeUndefined()
   })
 
-  it('every product DSN parses to the org key + its own project id', () => {
+  it('every product DSN parses to the caller key + its own project id', () => {
     for (const [product, projectId] of Object.entries(PRODUCT_PROJECT)) {
-      const parsed = parseDsn(dsnForProduct(product))
+      const parsed = parseDsn(dsnForProduct(product, KEY))
       expect(parsed, `${product} DSN must parse`).not.toBeNull()
       expect(parsed!.projectId, `${product} project id`).toBe(projectId)
-      expect(parsed!.publicKey, `${product} carries the org key`).toBe(HANZO_PUBLISHABLE_KEY)
+      expect(parsed!.publicKey, `${product} carries the resolved key`).toBe(KEY)
     }
   })
 })
 
 describe('DSN precedence — most specific source wins', () => {
-  it('lights up the error plane from `product` alone, with no dsn and no env', () => {
-    const a = createAnalytics({ product: 'console', enabled: false })
+  it('lights up the error plane from `product` + a resolved key, with no explicit dsn', () => {
+    const a = createAnalytics({ product: 'console', ingestKey: KEY, enabled: false })
     expect(a.errorPlaneEnabled).toBe(true)
     expect(a.errorIngestUrl).toContain(PRODUCT_PROJECT.console)
   })
 
   it('prefers an explicit dsn over both the env and the registry', () => {
     process.env[ENV] = OVERRIDE
-    const a = createAnalytics({ product: 'console', dsn: EXPLICIT, enabled: false })
+    const a = createAnalytics({ product: 'console', ingestKey: KEY, dsn: EXPLICIT, enabled: false })
     expect(a.errorIngestUrl).toContain('explicit-project')
   })
 
   it('prefers the env override over the registry, so a deploy can repoint a surface', () => {
     process.env[ENV] = OVERRIDE
-    const a = createAnalytics({ product: 'console', enabled: false })
+    const a = createAnalytics({ product: 'console', ingestKey: KEY, enabled: false })
     expect(a.errorIngestUrl).toContain('env-project')
   })
 
   it('stays inert for an unregistered product — never posts one surface into another project', () => {
-    const a = createAnalytics({ product: 'not-a-product', enabled: false })
+    const a = createAnalytics({ product: 'not-a-product', ingestKey: KEY, enabled: false })
+    expect(a.errorPlaneEnabled).toBe(false)
+    expect(a.errorIngestUrl).toBeUndefined()
+  })
+
+  it('stays inert with a product but no key — the error plane needs the live key', () => {
+    const a = createAnalytics({ product: 'console', enabled: false })
     expect(a.errorPlaneEnabled).toBe(false)
     expect(a.errorIngestUrl).toBeUndefined()
   })

package/src/dsn.ts

@@ -37,40 +37,20 @@ export const PRODUCT_PROJECT: Readonly<Record<string, string>> = Object.freeze({
   site: '019f9b1e-5785-7359-ad0b-f75db8e58c99', // hanzo.ai (marketing; product `site`)
 })
 
-/** dsnForProduct builds the product's Sentry DSN — the ONE org publishable key at
- *  its project's envelope endpoint — or undefined when the product has no project
- *  yet, which leaves the error plane inert rather than posting into the wrong one.
- *  Same key as the event stream: cloud resolves it to the org and attributes the
- *  errors there. */
-export function dsnForProduct(product: string | undefined): string | undefined {
-  if (!product) return undefined
+/** dsnForProduct builds the product's Sentry DSN from the caller's resolved
+ *  publishable `key` and the product's project — the SAME key the event stream
+ *  carries, at the product's envelope endpoint. Returns undefined when there is no
+ *  key or no project for the product, leaving the error plane inert rather than
+ *  posting into the wrong one. The key is NOT baked here: it is the value the
+ *  surface resolved (an explicit `ingestKey`, or the KMS-sourced
+ *  NEXT_PUBLIC_PUBLISHABLE_KEY the build inlines) — the ONE live source, never a
+ *  literal committed beside the code. */
+export function dsnForProduct(
+  product: string | undefined,
+  key: string | undefined
+): string | undefined {
+  if (!product || !key) return undefined
   const projectId = PRODUCT_PROJECT[product]
   if (!projectId) return undefined
-  return `https://${HANZO_PUBLISHABLE_KEY}@api.hanzo.ai/v1/sentry/${projectId}`
-}
-
-/** The hanzo org's publishable ingest key. Like the DSNs above it is PUBLIC by
- *  construction: write-only — it attributes a write and mints no reading
- *  principal — so it ships in the bundle and is readable in devtools, exactly as
- *  hanzo.id already inlines it. It is the value KMS holds at `deploy/PUBLISHABLE_KEY`
- *  and every fleet Dockerfile passes as the `PUBLISHABLE_KEY` build-arg; baking it
- *  as the default is the SAME move `dsnForProduct` makes for errors — a hanzo
- *  surface on the hanzo cloud emits attributed with zero wiring, and no build can
- *  ship unkeyed (the failure that files anonymous traffic under `$public`, which
- *  drops every track/identify/group and answers 200). */
-export const HANZO_PUBLISHABLE_KEY =
-  'pk-live-c88649f1085fb6ad441d8a0072933a9b'
-
-/** defaultPublishableKey resolves the baked hanzo key, but ONLY for the explicit
- *  hanzo cloud host (api.hanzo.ai) — the host the public, anonymous-traffic
- *  surfaces use. It is deliberately NOT applied to a same-origin `''` host: that
- *  is the shape a cookie/session app uses (it attributes signed-in users through
- *  the session, so it needs no anonymous key), AND it is the one host a
- *  white-label surface shares with hanzo, so defaulting it could attribute the
- *  wrong org. A custom host gets undefined. An explicit `ingestKey`, or an
- *  inlined NEXT_PUBLIC_PUBLISHABLE_KEY, still wins over this. */
-export function defaultPublishableKey(host: string | undefined): string | undefined {
-  return host === undefined || host === 'https://api.hanzo.ai'
-    ? HANZO_PUBLISHABLE_KEY
-    : undefined
+  return `https://${key}@api.hanzo.ai/v1/sentry/${projectId}`
 }

package/src/events.ts

@@ -69,3 +69,8 @@ export type EventName = (typeof EVENTS)[keyof typeof EVENTS]
 
 /** The reserved event name a pageview is stored under (server + read lens). */
 export const PAGEVIEW = '$pageview'
+
+/** The reserved name every captured exception is emitted under. Error Tracking
+ *  reads exactly this name; an exception emitted under its own message instead
+ *  makes every distinct message a permanent entry in the event taxonomy. */
+export const EXCEPTION = '$exception'

package/src/exception.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'vitest'
+import { digest, exceptionEntry, exceptionProperties, fingerprint } from './exception'
+
+/** A throwable with a realistic V8 stack, innermost call first (as V8 emits). */
+function boom(msg = 'Cannot read properties of undefined'): Error {
+  const e = new TypeError(msg)
+  e.stack = [
+    `TypeError: ${msg}`,
+    '    at loadIssue (https://hanzo.ai/_next/static/chunks/app.js:42:9)',
+    '    at render (https://hanzo.ai/_next/static/chunks/app.js:17:3)',
+    '    at vendorLoad (https://hanzo.ai/node_modules/react-dom/index.js:12:3)',
+  ].join('\n')
+  return e
+}
+
+describe('frame ordering — the product reads frames bottom-up', () => {
+  it('puts the entry point first and the throw site last', () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    const frames = e.stacktrace!.frames
+    // V8 emits innermost-first; the product wants the reverse.
+    expect(frames[0].mangled_name).toBe('vendorLoad')
+    expect(frames[frames.length - 1].mangled_name).toBe('loadIssue')
+  })
+
+  it('indexes the throw site at -1, which is where the issue list reads it', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_functions.at(-1)).toBe('loadIssue')
+    expect(p.$exception_sources.at(-1)).toBe('https://hanzo.ai/_next/static/chunks/app.js')
+  })
+})
+
+describe('stacktrace.type — the renderer draws nothing on any other value', () => {
+  it("is the literal 'resolved'", () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    expect(e.stacktrace!.type).toBe('resolved')
+  })
+
+  it('is omitted entirely when there is no stack, rather than sent empty', () => {
+    const e = exceptionEntry('Script error.', { handled: false, id: 'x' })
+    expect(e.stacktrace).toBeUndefined()
+    expect(e.type).toBe('Error')
+    expect(e.value).toBe('Script error.')
+  })
+})
+
+describe('in_app — frames without it are hidden by default', () => {
+  it('marks first-party code in_app and vendor code not', () => {
+    const frames = exceptionEntry(boom(), { handled: false, id: 'x' }).stacktrace!.frames
+    const byName = Object.fromEntries(frames.map((f) => [f.mangled_name, f.in_app]))
+    expect(byName.loadIssue).toBe(true)
+    expect(byName.render).toBe(true)
+    expect(byName.vendorLoad).toBe(false)
+  })
+
+  it('keeps only in_app frames out of the fingerprint', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    // vendorLoad is the only non-in_app frame; it must not move the group key.
+    const e = exceptionEntry(boom(), { handled: false, id: 'y' })
+    e.stacktrace!.frames = e.stacktrace!.frames.filter((f) => f.in_app)
+    expect(fingerprint(e)).toBe(p.$exception_fingerprint)
+  })
+})
+
+describe('fingerprint — the issue grouping key', () => {
+  it('is present, since the issue query drops events without one', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_fingerprint).toMatch(/^[0-9a-f]{32}$/)
+  })
+
+  it('groups the SAME bug whose message varies — the whole point', () => {
+    // The real-world case: one failed-chunk bug produced a distinct event name per
+    // chunk id. These must be one issue.
+    const a = new Error('Loading chunk 3324 failed.')
+    const b = new Error('Loading chunk 998 failed.')
+    const stack = '    at load (https://hanzo.ai/app.js:1:1)'
+    a.stack = `Error: x\n${stack}`
+    b.stack = `Error: y\n${stack}`
+    const fa = exceptionProperties(a, { handled: false, id: '1' }).$exception_fingerprint
+    const fb = exceptionProperties(b, { handled: false, id: '2' }).$exception_fingerprint
+    expect(fa).toBe(fb)
+  })
+
+  it('separates genuinely different bugs', () => {
+    const other = new RangeError('nope')
+    other.stack = 'RangeError: nope\n    at somewhereElse (https://hanzo.ai/other.js:5:5)'
+    const fa = exceptionProperties(boom(), { handled: false, id: '1' }).$exception_fingerprint
+    const fb = exceptionProperties(other, { handled: false, id: '2' }).$exception_fingerprint
+    expect(fa).not.toBe(fb)
+  })
+
+  it('still groups stackless errors by type instead of scattering them', () => {
+    const f1 = exceptionProperties('Script error.', { handled: false, id: '1' })
+    const f2 = exceptionProperties('Script error.', { handled: false, id: '2' })
+    expect(f1.$exception_fingerprint).toBe(f2.$exception_fingerprint)
+  })
+})
+
+describe('raw_id — frame identity', () => {
+  it('carries the "<hash>/<part>" shape the product expects', () => {
+    const frames = exceptionEntry(boom(), { handled: false, id: 'x' }).stacktrace!.frames
+    for (const f of frames) expect(f.raw_id).toMatch(/^[0-9a-f]{32}\/0$/)
+  })
+
+  it('is stable for the same code location across captures', () => {
+    const a = exceptionEntry(boom(), { handled: false, id: '1' }).stacktrace!.frames
+    const b = exceptionEntry(boom('different message'), { handled: false, id: '2' })
+      .stacktrace!.frames
+    expect(a.map((f) => f.raw_id)).toEqual(b.map((f) => f.raw_id))
+  })
+})
+
+describe('mechanism + level', () => {
+  it('reports an uncaught error as unhandled', () => {
+    const e = exceptionEntry(boom(), { handled: false, id: 'x' })
+    expect(e.mechanism).toEqual({ type: 'generic', handled: false, synthetic: false })
+  })
+
+  it('marks a non-Error throwable synthetic', () => {
+    const e = exceptionEntry('just a string', { handled: true, id: 'x' })
+    expect(e.mechanism?.synthetic).toBe(true)
+  })
+
+  it('defaults level to error and honours an override', () => {
+    expect(exceptionProperties(boom(), { handled: true, id: 'x' }).$exception_level).toBe('error')
+    expect(
+      exceptionProperties(boom(), { handled: true, id: 'x', level: 'warning' }).$exception_level,
+    ).toBe('warning')
+  })
+})
+
+describe('denormalized properties (nothing derives these server-side here)', () => {
+  it('sends the search + issue-column arrays the product reads', () => {
+    const p = exceptionProperties(boom(), { handled: false, id: 'x' })
+    expect(p.$exception_types).toEqual(['TypeError'])
+    expect(p.$exception_values).toEqual(['Cannot read properties of undefined'])
+    expect(p.$exception_type).toBe('TypeError')
+    expect(p.$exception_handled).toBe(false)
+    expect(p.$exception_fingerprint_record).toEqual([{ type: 'manual' }])
+    expect(p.$exception_list).toHaveLength(1)
+  })
+})
+
+describe('hostile input never escapes', () => {
+  it('survives a throwable whose getters throw', () => {
+    const hostile = {
+      get name() {
+        throw new Error('nope')
+      },
+      get message() {
+        throw new Error('nope')
+      },
+      get stack() {
+        throw new Error('nope')
+      },
+    }
+    expect(() => exceptionProperties(hostile, { handled: true, id: 'x' })).not.toThrow()
+  })
+
+  it('bounds an enormous message', () => {
+    const e = exceptionEntry(new Error('x'.repeat(100_000)), { handled: true, id: 'x' })
+    expect(e.value.length).toBeLessThanOrEqual(4096)
+  })
+
+  it('bounds frame count', () => {
+    const many = new Error('deep')
+    many.stack =
+      'Error: deep\n' +
+      Array.from({ length: 500 }, (_, i) => `    at f${i} (https://hanzo.ai/a.js:${i}:1)`).join(
+        '\n',
+      )
+    expect(exceptionEntry(many, { handled: true, id: 'x' }).stacktrace!.frames.length).toBe(50)
+  })
+})
+
+describe('digest', () => {
+  it('is stable and 32 hex chars', () => {
+    expect(digest('abc')).toBe(digest('abc'))
+    expect(digest('abc')).toMatch(/^[0-9a-f]{32}$/)
+  })
+
+  it('separates different inputs', () => {
+    expect(digest('abc')).not.toBe(digest('abd'))
+  })
+
+  it('handles an empty string', () => {
+    expect(digest('')).toMatch(/^[0-9a-f]{32}$/)
+  })
+})