@hanzo/event 0.3.6 → 0.3.9

package/src/storage.ts

@@ -3,6 +3,7 @@
 // client imports cleanly in a Next.js server component.
 
 import type { Attribution, Cohort } from './types'
+import { uuidv7 } from './uid'
 
 const KEY = {
   anon: 'hz_anon_id',
@@ -23,19 +24,13 @@ function ls(): Storage | undefined {
   }
 }
 
-function uid(): string {
-  const c = typeof crypto !== 'undefined' ? crypto : undefined
-  if (c && 'randomUUID' in c) return c.randomUUID()
-  return 'a-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10)
-}
-
 /** Stable anonymous id, minted once per browser and reused across sessions. */
 export function anonId(): string | undefined {
   const s = ls()
   if (!s) return undefined
   let v = s.getItem(KEY.anon)
   if (!v) {
-    v = uid()
+    v = uuidv7()
     s.setItem(KEY.anon, v)
   }
   return v
@@ -46,7 +41,14 @@ interface SessionState {
   last: number
 }
 
-/** Current session id, rotated after SESSION_TTL_MS of inactivity. */
+/**
+ * Current session id, rotated after SESSION_TTL_MS of inactivity.
+ *
+ * Minted at `now`, so the v7 timestamp the id carries IS the session's start
+ * instant — which is what the session rollups partition and order on. Passing the
+ * caller's clock rather than reading Date.now() again keeps the id's embedded time
+ * and the recorded `last` from disagreeing.
+ */
 export function sessionId(now = Date.now()): string | undefined {
   const s = ls()
   if (!s) return undefined
@@ -57,7 +59,7 @@ export function sessionId(now = Date.now()): string | undefined {
     state = null
   }
   if (!state || now - state.last > SESSION_TTL_MS) {
-    state = { id: uid(), last: now }
+    state = { id: uuidv7(now), last: now }
   } else {
     state.last = now
   }

package/src/uid.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, afterEach } from 'vitest'
+import { uuidv7, uuidv7Time } from './uid'
+import { eventId } from './sentry'
+
+/** The event plane's admission gate, transcribed from the session rollup's own SQL:
+ *  `bitAnd(bitShiftRight(toUInt128(accurateCastOrNull(id,'UUID')), 76), 15) = 7`.
+ *  An id that fails this is dropped by the materialized view without an error. */
+const versionNibble = (id: string): bigint => (BigInt('0x' + id.replace(/-/g, '')) >> 76n) & 15n
+
+/** The session start the rollup partitions and orders on:
+ *  `fromUnixTimestamp(intDiv(toUInt64(bitShiftRight(session_id_v7, 80)), 1000))`. */
+const embeddedMs = (id: string): bigint => BigInt('0x' + id.replace(/-/g, '')) >> 80n
+
+/** RFC 9562 variant: the two high bits of octet 8 are 0b10. */
+const variantBits = (id: string): bigint => (BigInt('0x' + id.replace(/-/g, '')) >> 62n) & 3n
+
+const SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+describe('uuidv7', () => {
+  const realCrypto = globalThis.crypto
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'crypto', { value: realCrypto, configurable: true })
+  })
+
+  it('passes the plane admission gate that v4 fails', () => {
+    for (let i = 0; i < 200; i++) expect(versionNibble(uuidv7())).toBe(7n)
+    // The gate is real: crypto.randomUUID (v4) is what the SDK used to mint.
+    expect(versionNibble(crypto.randomUUID())).toBe(4n)
+  })
+
+  it('carries the mint instant the rollup keys on', () => {
+    for (const ms of [0, 1, 1_000, Date.now(), 253_402_300_799_000]) {
+      const id = uuidv7(ms)
+      expect(embeddedMs(id)).toBe(BigInt(ms))
+      expect(uuidv7Time(id)).toBe(ms)
+    }
+  })
+
+  it('sets the RFC 9562 variant', () => {
+    for (let i = 0; i < 50; i++) expect(variantBits(uuidv7())).toBe(2n)
+  })
+
+  it('sorts lexically by time', () => {
+    const t = Date.now()
+    const ids = [t + 3000, t, t + 1000, t + 2000].map((ms) => uuidv7(ms))
+    expect([...ids].sort()).toEqual([ids[1], ids[2], ids[3], ids[0]])
+  })
+
+  it('is unique within a single millisecond', () => {
+    const ms = Date.now()
+    const seen = new Set(Array.from({ length: 5000 }, () => uuidv7(ms)))
+    expect(seen.size).toBe(5000)
+  })
+
+  it('keeps a valid v7 shape with no crypto at all', () => {
+    Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+    const id = uuidv7(1_700_000_000_000)
+    // The old fallback emitted 'a-<base36>', which the plane casts to NULL and drops
+    // by the same gate v4 fails. Only entropy may degrade — never the shape.
+    expect(id).toMatch(SHAPE)
+    expect(versionNibble(id)).toBe(7n)
+    expect(embeddedMs(id)).toBe(1_700_000_000_000n)
+  })
+})
+
+describe('eventId', () => {
+  it('is the one minter formatted for the Sentry wire', () => {
+    const id = eventId()
+    expect(id).toMatch(/^[0-9a-f]{32}$/)
+    const dashed = `${id.slice(0, 8)}-${id.slice(8, 12)}-${id.slice(12, 16)}-${id.slice(16, 20)}-${id.slice(20)}`
+    expect(versionNibble(dashed)).toBe(7n)
+  })
+})

package/src/uid.ts

@@ -0,0 +1,70 @@
+// The ONE id minter for this client — UUIDv7 (RFC 9562 §5.7).
+//
+// WHY NOT crypto.randomUUID(): it mints v4, whose 122 bits are pure entropy and
+// carry no time. The session rollups on the event plane derive a session's start
+// instant FROM THE ID — their PARTITION BY and ORDER BY are
+// `fromUnixTimestamp(intDiv(toUInt64(bitShiftRight(session_id_v7, 80)), 1000))` —
+// so they admit only ids whose version nibble is 7
+// (`bitAnd(bitShiftRight(toUInt128(session_id), 76), 15) = 7`). A v4 session id is
+// not merely unordered there: it is DISCARDED at the door, silently, and the
+// rollup stays empty forever. Minting v7 is the whole reason those rollups can
+// exist; it also clusters index writes by time instead of scattering them across
+// the keyspace.
+//
+// Layout, 16 bytes big-endian:
+//   0..5   unix_ts_ms — 48-bit millisecond timestamp
+//   6      0111 (version 7) in the high nibble | rand_a
+//   7      rand_a
+//   8      10 (variant) in the high 2 bits | rand_b
+//   9..15  rand_b
+//
+// Never returns a non-UUID shape. The old minters fell back to `'a-' + base36`
+// when crypto was absent, and the plane casts a session id with
+// accurateCastOrNull(…, 'UUID') — a shape that does not parse becomes NULL and is
+// dropped by the same gate, so the fallback failed exactly like v4 did. Here only
+// the ENTROPY degrades without crypto; the shape is always a valid v7 UUID.
+
+/** 00..ff, so formatting is a lookup rather than 16 padStart calls. */
+const HEX: string[] = Array.from({ length: 256 }, (_, i) => (i + 0x100).toString(16).slice(1))
+
+/** Cryptographic randomness when the host has it, Math.random when it does not. */
+function fill(b: Uint8Array): Uint8Array {
+  const c = typeof crypto !== 'undefined' ? crypto : undefined
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(b)
+    return b
+  }
+  for (let i = 0; i < b.length; i++) b[i] = (Math.random() * 256) | 0
+  return b
+}
+
+/**
+ * uuidv7 mints a time-ordered UUIDv7 for `now` (epoch milliseconds).
+ *
+ * Two ids minted in the same millisecond sort arbitrarily between themselves; ids
+ * from different milliseconds sort by time, lexically and numerically alike.
+ */
+export function uuidv7(now: number = Date.now()): string {
+  const b = fill(new Uint8Array(16))
+  // 48-bit big-endian timestamp. Milliseconds stay exact well past year 10000, so
+  // the arithmetic never leaves the safe-integer range.
+  let t = Math.floor(now)
+  for (let i = 5; i >= 0; i--) {
+    b[i] = t % 256
+    t = Math.floor(t / 256)
+  }
+  b[6] = 0x70 | (b[6] & 0x0f) // version 7
+  b[8] = 0x80 | (b[8] & 0x3f) // variant 0b10
+  return (
+    HEX[b[0]] + HEX[b[1]] + HEX[b[2]] + HEX[b[3]] + '-' +
+    HEX[b[4]] + HEX[b[5]] + '-' +
+    HEX[b[6]] + HEX[b[7]] + '-' +
+    HEX[b[8]] + HEX[b[9]] + '-' +
+    HEX[b[10]] + HEX[b[11]] + HEX[b[12]] + HEX[b[13]] + HEX[b[14]] + HEX[b[15]]
+  )
+}
+
+/** The millisecond timestamp a v7 id was minted at — the inverse of uuidv7. */
+export function uuidv7Time(id: string): number {
+  return parseInt(id.slice(0, 8) + id.slice(9, 13), 16)
+}

package/src/version.ts

@@ -1,4 +1,4 @@
 // The library version, stamped on every event (`libraryVersion`) and on the
 // Sentry `sdk` block. It lives alone so `sentry.ts` can read it without importing
 // `core.ts` — core imports sentry, so the reverse would be an import cycle.
-export const VERSION = '0.3.6'
+export const VERSION = '0.3.9'