@zuplo/cli 7.7.8 → 7.7.9

package/node_modules/@posthog/core/src/traces/config.spec.ts

@@ -0,0 +1,271 @@
+import { createMockLogger } from '@/testing'
+import { resolveTracesConfig } from './config'
+
+describe('resolveTracesConfig', () => {
+  it.each([
+    ['zero', 0],
+    ['negative', -1],
+    ['not a number', NaN],
+    // Floored, these read as 1, 2 and 3 — caps an order of magnitude below what
+    // the caller wrote, applied silently.
+    ['a fraction', 1.5],
+    ['a large fraction', 200.5],
+    ['infinity', Infinity],
+  ])('falls back to the default per-span caps when given %s', (_label, value) => {
+    const resolved = resolveTracesConfig({
+      maxAttributesPerSpan: value,
+      maxEventsPerSpan: value,
+      maxAttributeValueLength: value,
+    })
+    expect(resolved.maxAttributesPerSpan).toBe(128)
+    expect(resolved.maxEventsPerSpan).toBe(128)
+    expect(resolved.maxAttributeValueLength).toBe(8192)
+  })
+
+  it('honours explicit per-span caps', () => {
+    // Without this the resolver can ignore maxEventsPerSpan entirely and every
+    // other test still passes, because they all assert the default.
+    expect(resolveTracesConfig({ maxAttributesPerSpan: 5, maxEventsPerSpan: 7 })).toMatchObject({
+      maxAttributesPerSpan: 5,
+      maxEventsPerSpan: 7,
+    })
+  })
+
+  it('keeps the per-event attribute cap fixed', () => {
+    // The cap is internal, so an untyped caller naming it gets the default.
+    expect(resolveTracesConfig({ maxAttributesPerEvent: 9 } as any).maxAttributesPerEvent).toBe(128)
+  })
+
+  it('applies the documented defaults', () => {
+    expect(resolveTracesConfig(undefined)).toMatchObject({
+      flushIntervalMs: 5000,
+      maxExportBatchSize: 512,
+      maxQueueSize: 2048,
+      maxAttributesPerSpan: 128,
+      maxEventsPerSpan: 128,
+      maxAttributesPerEvent: 128,
+      maxAttributeValueLength: 8192,
+      maxLiveSpans: 10_000,
+      maxSpanAgeMs: 3_600_000,
+    })
+  })
+
+  it('honours an explicit attribute value bound', () => {
+    expect(resolveTracesConfig({ maxAttributeValueLength: 256 }).maxAttributeValueLength).toBe(256)
+  })
+
+  it('honours explicit live-span bounds', () => {
+    expect(resolveTracesConfig({ maxLiveSpans: 50, maxSpanAgeMs: 30_000 })).toMatchObject({
+      maxLiveSpans: 50,
+      maxSpanAgeMs: 30_000,
+    })
+  })
+
+  it.each([0, -1, Number.NaN])('falls back to the defaults for unusable live-span bounds (%p)', (value) => {
+    expect(resolveTracesConfig({ maxLiveSpans: value, maxSpanAgeMs: value })).toMatchObject({
+      maxLiveSpans: 10_000,
+      maxSpanAgeMs: 3_600_000,
+    })
+  })
+
+  it('leaves serviceName unset so core supplies unknown_service', () => {
+    expect(resolveTracesConfig({}).serviceName).toBeUndefined()
+  })
+
+  it('honours explicit values', () => {
+    expect(
+      resolveTracesConfig({ serviceName: 'checkout', flushIntervalMs: 1000, maxExportBatchSize: 50 })
+    ).toMatchObject({
+      serviceName: 'checkout',
+      flushIntervalMs: 1000,
+      maxExportBatchSize: 50,
+    })
+  })
+
+  it('lets OTLP resource attributes override the named fields', () => {
+    const resolved = resolveTracesConfig({
+      serviceName: 'named',
+      serviceVersion: '1.0.0',
+      environment: 'staging',
+      resourceAttributes: {
+        'service.name': 'from-attributes',
+        'service.version': '2.0.0',
+        'deployment.environment': 'production',
+      },
+    })
+
+    expect(resolved.serviceName).toBe('from-attributes')
+    expect(resolved.serviceVersion).toBe('2.0.0')
+    expect(resolved.environment).toBe('production')
+  })
+
+  it.each([0, -1, 0.5, Number.NaN, Number.POSITIVE_INFINITY])(
+    'falls back to the default for an unusable maxExportBatchSize (%p)',
+    (value) => {
+      // A non-positive batch size reaches an export loop that cannot make
+      // progress with it, so it spins forever posting empty batches.
+      expect(resolveTracesConfig({ maxExportBatchSize: value }).maxExportBatchSize).toBe(512)
+    }
+  )
+
+  it('takes the default for a fractional batch size rather than flooring it', () => {
+    // Every numeric knob resolves the same way, so a fraction is a value the
+    // caller did not mean rather than one to round down behind their back.
+    expect(resolveTracesConfig({ maxExportBatchSize: 10.9 }).maxExportBatchSize).toBe(512)
+  })
+
+  it.each([0, -1, 1.5, Number.NaN])('falls back to the default for an unusable flushIntervalMs (%p)', (value) => {
+    expect(resolveTracesConfig({ flushIntervalMs: value }).flushIntervalMs).toBe(5000)
+  })
+
+  it.each([0.5, 10_000.5])('falls back to the defaults for fractional live-span bounds (%p)', (value) => {
+    expect(resolveTracesConfig({ maxLiveSpans: value, maxSpanAgeMs: value })).toMatchObject({
+      maxLiveSpans: 10_000,
+      maxSpanAgeMs: 3_600_000,
+    })
+  })
+
+  it('keeps the queue at least as large as the export batch', () => {
+    // A queue smaller than the flush trigger would stop the depth-based flush
+    // from ever firing.
+    expect(resolveTracesConfig({ maxExportBatchSize: 5000 }).maxQueueSize).toBe(5000)
+    expect(resolveTracesConfig({ maxExportBatchSize: 10 }).maxQueueSize).toBe(2048)
+  })
+
+  it('honours an explicit maxQueueSize', () => {
+    expect(resolveTracesConfig({ maxQueueSize: 100_000 }).maxQueueSize).toBe(100_000)
+  })
+
+  it('floors an explicit maxQueueSize at the export batch size', () => {
+    expect(resolveTracesConfig({ maxExportBatchSize: 512, maxQueueSize: 10 }).maxQueueSize).toBe(512)
+  })
+
+  it('attaches the host resource attributes the entrypoint supplies', () => {
+    expect(
+      resolveTracesConfig(undefined, { 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' }).resourceAttributes
+    ).toEqual({ 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' })
+  })
+
+  it('lets user resource attributes override the host ones', () => {
+    expect(
+      resolveTracesConfig(
+        { resourceAttributes: { 'os.name': 'my-os', 'os.version': '1.2.3' } },
+        { 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' }
+      ).resourceAttributes
+    ).toEqual({ 'os.name': 'my-os', 'os.version': '1.2.3' })
+  })
+
+  it('resolves when the entrypoint supplies no host attributes', () => {
+    expect(resolveTracesConfig({ resourceAttributes: { 'host.name': 'worker-01' } }).resourceAttributes).toEqual({
+      'host.name': 'worker-01',
+    })
+  })
+})
+
+describe('resourceAttributes guarding', () => {
+  it('ignores a non-object value', () => {
+    const { resourceAttributes } = resolveTracesConfig({ resourceAttributes: 'oops' as never })
+
+    expect(Object.keys(resourceAttributes ?? {})).toEqual([])
+  })
+
+  it('ignores an array, which would otherwise spread as numeric keys', () => {
+    const { resourceAttributes } = resolveTracesConfig({
+      resourceAttributes: [{ key: 'service.name' }] as never,
+    })
+
+    expect(Object.keys(resourceAttributes ?? {})).not.toContain('0')
+  })
+
+  it('drops an identity key that is not a string', () => {
+    const resolved = resolveTracesConfig({
+      serviceName: 'checkout-api',
+      resourceAttributes: { 'service.name': 12345 as never, region: 'us' },
+    })
+
+    expect(resolved.serviceName).toBe('checkout-api')
+    expect(resolved.resourceAttributes).toEqual({ region: 'us' })
+  })
+
+  it('ignores a beforeSpanSend entry that is not a function', () => {
+    // A plain-JS caller passing the wrong shape would otherwise have every span
+    // dropped by a hook that throws on call, with tracing silently off.
+    const scrub = (span: any): any => span
+    const resolved = resolveTracesConfig({ beforeSpanSend: ['not a function', scrub] as never })
+
+    expect(resolved.beforeSpanSend).toEqual([scrub])
+  })
+
+  it('warns about a dropped hook, since the redaction it was configured for is gone', () => {
+    const logger = createMockLogger()
+    const scrub = (span: any): any => span
+
+    resolveTracesConfig({ beforeSpanSend: ['not a function', scrub] as never }, undefined, logger)
+
+    // `critical`, not `warn`: every other level is gated behind `debug: true`.
+    expect(logger.critical).toHaveBeenCalledWith(expect.stringContaining('ignoring 1 of 2 entries'))
+  })
+
+  it('stays quiet for a conditionally disabled hook', () => {
+    // `[featureEnabled && scrub]` is ordinary JS; nothing was configured to
+    // redact, so claiming redaction is broken would be false alarm.
+    const logger = createMockLogger()
+
+    const resolved = resolveTracesConfig({ beforeSpanSend: [false, null, undefined] as never }, undefined, logger)
+
+    expect(resolved.beforeSpanSend).toEqual([])
+    expect(logger.critical).not.toHaveBeenCalled()
+  })
+
+  it('stays quiet when every hook is callable', () => {
+    const logger = createMockLogger()
+
+    resolveTracesConfig({ beforeSpanSend: [(span: any): any => span] }, undefined, logger)
+
+    expect(logger.critical).not.toHaveBeenCalled()
+  })
+
+  it('resolves to no hooks when beforeSpanSend is the wrong type entirely', () => {
+    const resolved = resolveTracesConfig({ beforeSpanSend: { scrub: true } as never })
+
+    expect(resolved.beforeSpanSend).toEqual([])
+  })
+
+  it('does not throw when an identity accessor throws', () => {
+    const hostile = {}
+    Object.defineProperty(hostile, 'service.name', {
+      enumerable: true,
+      get() {
+        throw new Error('config getter exploded')
+      },
+    })
+
+    expect(() => resolveTracesConfig({ resourceAttributes: hostile as never })).not.toThrow()
+  })
+
+  it('does not throw when a non-identity accessor throws', () => {
+    const hostile = { 'service.name': 'checkout-api' }
+    Object.defineProperty(hostile, 'region', {
+      enumerable: true,
+      get() {
+        throw new Error('config getter exploded')
+      },
+    })
+
+    expect(() => resolveTracesConfig({ resourceAttributes: hostile as never }, { 'os.name': 'Linux' })).not.toThrow()
+  })
+
+  it('keeps the readable attributes when one accessor throws', () => {
+    const hostile = { region: 'us' }
+    Object.defineProperty(hostile, 'tenant', {
+      enumerable: true,
+      get() {
+        throw new Error('config getter exploded')
+      },
+    })
+
+    const resolved = resolveTracesConfig({ resourceAttributes: hostile as never }, { 'os.name': 'Linux' })
+
+    expect(resolved.resourceAttributes).toMatchObject({ 'os.name': 'Linux', region: 'us' })
+  })
+})

package/node_modules/@posthog/core/src/traces/config.ts

@@ -0,0 +1,142 @@
+import { assignUserAttributes } from '../utils/json-utils'
+import type { ResolvedTracesConfig } from './types'
+import type { BeforeSpanSendFn, TracesConfig } from '@posthog/types'
+import type { Logger } from '../types'
+
+// OpenTelemetry's BatchSpanProcessor defaults, which sit comfortably under the
+// server's request body cap.
+const DEFAULT_FLUSH_INTERVAL_MS = 5000
+const DEFAULT_MAX_EXPORT_BATCH_SIZE = 512
+const DEFAULT_MAX_QUEUE_SIZE = 2048
+// OpenTelemetry's per-span defaults.
+const DEFAULT_MAX_ATTRIBUTES_PER_SPAN = 128
+const DEFAULT_MAX_EVENTS_PER_SPAN = 128
+// OpenTelemetry's per-event limit, which is the same number. Fixed rather than
+// configurable: `maxAttributesPerSpan` and `maxEventsPerSpan` already give a
+// caller room to shape a span, and this one only has to stop an event holding
+// an unbounded bag.
+const DEFAULT_MAX_ATTRIBUTES_PER_EVENT = 128
+// OpenTelemetry leaves the value length unlimited, which is what lets one
+// multi-MB attribute make a span too large for the endpoint to accept — and an
+// oversized span is dropped whole. 8 KB bounds a single string: it holds a deep
+// stack trace and any realistic header, query string or payload excerpt, and
+// keeps a span's own attributes under 1 MB at the attribute cap. A span's total
+// size is the product of these caps; the body limit itself is enforced at the
+// batch boundary, which is where the whole payload can be weighed at once.
+const DEFAULT_MAX_ATTRIBUTE_VALUE_LENGTH = 8192
+
+// Live-span bounds. A server can legitimately hold thousands of spans open at
+// once, and refusing a legitimate span is worse than tolerating a leak, so the
+// count bound sits well above realistic concurrency — affordable because live
+// accounting is an id and a timestamp per span, not the span. The age bound is
+// an hour: production traces routinely run past ten minutes, and a span still
+// open after an hour is a leak rather than slow work.
+const DEFAULT_MAX_LIVE_SPANS = 10_000
+const DEFAULT_MAX_SPAN_AGE_MS = 3_600_000
+
+/**
+ * Coerces a caller-supplied positive-integer option. `0`, a negative, or `NaN`
+ * reaching the export loop would stall it.
+ *
+ * A fraction takes the default rather than being floored: these are documented
+ * as positive integers, and silently reading `maxAttributesPerSpan: 1.5` as `1`
+ * caps a span an order of magnitude below what the caller wrote.
+ */
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : fallback
+}
+
+const IDENTITY_KEYS = ['service.name', 'service.version', 'deployment.environment'] as const
+
+/**
+ * Drops a non-string identity key rather than letting it through: the resolver
+ * would ignore it, and it would still reach the wire as an int and leave the
+ * spans unattributable.
+ */
+function withUsableIdentityKeys(attributes: TracesConfig['resourceAttributes']): TracesConfig['resourceAttributes'] {
+  // A primitive or array would otherwise be spread into attributes keyed "0", "1", "2".
+  if (!attributes || typeof attributes !== 'object' || Array.isArray(attributes)) {
+    return undefined
+  }
+  try {
+    if (IDENTITY_KEYS.every((key) => !(key in attributes) || typeof attributes[key] === 'string')) {
+      return attributes
+    }
+    const usable = { ...attributes }
+    for (const key of IDENTITY_KEYS) {
+      if (key in usable && typeof usable[key] !== 'string') {
+        delete usable[key]
+      }
+    }
+    return usable
+  } catch {
+    // A throwing accessor on the config object must not escape `startSpan`.
+    return undefined
+  }
+}
+
+/**
+ * Keeps only the callable hooks. Anything else is dropped rather than called: an
+ * untyped caller passing the wrong shape would otherwise have every span dropped
+ * by a hook that throws, leaving tracing silently off.
+ *
+ * Reported at `critical` rather than thrown on: a constructor that throws takes
+ * the application down, but every other log level is gated behind `debug: true`,
+ * and an inert redaction hook ships the values it was meant to remove.
+ */
+function resolveBeforeSpanSend(beforeSpanSend: TracesConfig['beforeSpanSend'], logger?: Logger): BeforeSpanSendFn[] {
+  if (!beforeSpanSend) {
+    return []
+  }
+  // `[featureEnabled && scrub]` is ordinary JS, and a caller who wrote it did not
+  // configure a hook at all — only a value that was meant to be one is worth
+  // shouting about.
+  const supplied = [beforeSpanSend].flat().filter((hook) => Boolean(hook))
+  const hooks = supplied.filter((hook): hook is BeforeSpanSendFn => typeof hook === 'function')
+  if (hooks.length !== supplied.length) {
+    logger?.critical(
+      `beforeSpanSend: ignoring ${supplied.length - hooks.length} of ${supplied.length} entries that are not functions. ` +
+        'Spans export without them, so whatever they were redacting is not redacted.'
+    )
+  }
+  return hooks
+}
+
+/**
+ * Resolves the public `traces` config into the shape core `PostHogTraces` consumes.
+ * OTLP resource attributes take precedence over the named fields, matching the
+ * logs config. `hostResourceAttributes` are runtime-detected by the entrypoint and
+ * merge first, so a user-supplied value of the same key wins.
+ *
+ * @internal Exposed for cross-package use within this SDK; not part of the stable public API.
+ */
+export function resolveTracesConfig(
+  config: TracesConfig | undefined,
+  hostResourceAttributes?: Record<string, string>,
+  logger?: Logger
+): ResolvedTracesConfig {
+  // Copied key by key rather than spread: a throwing accessor on a user-supplied
+  // attribute would otherwise escape the first `startSpan`.
+  const resourceAttributes = assignUserAttributes(
+    { ...hostResourceAttributes },
+    withUsableIdentityKeys(config?.resourceAttributes)
+  )
+  const maxExportBatchSize = positiveInteger(config?.maxExportBatchSize, DEFAULT_MAX_EXPORT_BATCH_SIZE)
+  return {
+    serviceName: (resourceAttributes?.['service.name'] as string | undefined) ?? config?.serviceName,
+    serviceVersion: (resourceAttributes?.['service.version'] as string | undefined) ?? config?.serviceVersion,
+    environment: (resourceAttributes?.['deployment.environment'] as string | undefined) ?? config?.environment,
+    resourceAttributes,
+    beforeSpanSend: resolveBeforeSpanSend(config?.beforeSpanSend, logger),
+    maxAttributesPerSpan: positiveInteger(config?.maxAttributesPerSpan, DEFAULT_MAX_ATTRIBUTES_PER_SPAN),
+    maxEventsPerSpan: positiveInteger(config?.maxEventsPerSpan, DEFAULT_MAX_EVENTS_PER_SPAN),
+    maxAttributesPerEvent: DEFAULT_MAX_ATTRIBUTES_PER_EVENT,
+    maxAttributeValueLength: positiveInteger(config?.maxAttributeValueLength, DEFAULT_MAX_ATTRIBUTE_VALUE_LENGTH),
+    flushIntervalMs: positiveInteger(config?.flushIntervalMs, DEFAULT_FLUSH_INTERVAL_MS),
+    maxExportBatchSize,
+    // Never below the flush trigger, or the depth-based flush could never fire.
+    maxQueueSize: Math.max(positiveInteger(config?.maxQueueSize, DEFAULT_MAX_QUEUE_SIZE), maxExportBatchSize),
+    maxLiveSpans: positiveInteger(config?.maxLiveSpans, DEFAULT_MAX_LIVE_SPANS),
+    maxSpanAgeMs: positiveInteger(config?.maxSpanAgeMs, DEFAULT_MAX_SPAN_AGE_MS),
+  }
+}

package/node_modules/@posthog/core/src/traces/context.ts

@@ -0,0 +1,30 @@
+import type { Span } from '@posthog/types'
+import type { SpanContextManager } from './types'
+
+/**
+ * Synchronous active-span tracking: restores the previous active span when the
+ * callback returns, which for an async callback means when it returns its
+ * promise — so spans started after an `await` won't see it as active.
+ *
+ * The fallback for runtimes with no ambient async context; Node injects an
+ * `AsyncLocalStorage`-backed manager instead. `parent` is the escape hatch.
+ *
+ * @internal Exposed for cross-package use within this SDK; not part of the stable public API.
+ */
+export class SyncSpanContextManager implements SpanContextManager {
+  private _active: Span | undefined
+
+  active(): Span | undefined {
+    return this._active
+  }
+
+  with<T>(span: Span, fn: () => T): T {
+    const previous = this._active
+    this._active = span
+    try {
+      return fn()
+    } finally {
+      this._active = previous
+    }
+  }
+}

package/node_modules/@posthog/core/src/traces/ids.spec.ts

@@ -0,0 +1,115 @@
+import { getRandomBytes, isValidSpanId, isValidTraceId, newSpanId, newTraceId } from './ids'
+
+describe('trace and span ids', () => {
+  describe('newTraceId', () => {
+    it('is 32 lowercase hex characters', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+      }
+    })
+
+    it('is never all zeros', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newTraceId()).not.toBe('0'.repeat(32))
+      }
+    })
+
+    it('does not repeat', () => {
+      const ids = new Set(Array.from({ length: 200 }, newTraceId))
+      expect(ids.size).toBe(200)
+    })
+  })
+
+  describe('newSpanId', () => {
+    it('is 16 lowercase hex characters', () => {
+      for (let i = 0; i < 50; i++) {
+        expect(newSpanId()).toMatch(/^[0-9a-f]{16}$/)
+      }
+    })
+
+    it('does not repeat', () => {
+      const ids = new Set(Array.from({ length: 200 }, newSpanId))
+      expect(ids.size).toBe(200)
+    })
+  })
+
+  describe('getRandomBytes', () => {
+    it('returns the requested length', () => {
+      expect(getRandomBytes(8)).toHaveLength(8)
+      expect(getRandomBytes(16)).toHaveLength(16)
+    })
+
+    it('falls back to Math.random when crypto is unavailable', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      // React Native has no global crypto without a polyfill — the fallback path
+      // is what keeps span ids working there.
+      Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true })
+      try {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+        expect(newSpanId()).toMatch(/^[0-9a-f]{16}$/)
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+
+    it('falls back when getRandomValues throws', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      Object.defineProperty(globalThis, 'crypto', {
+        value: {
+          getRandomValues: () => {
+            throw new Error('not allowed')
+          },
+        },
+        configurable: true,
+      })
+      try {
+        expect(newTraceId()).toMatch(/^[0-9a-f]{32}$/)
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+
+    it('never emits an all-zero id even when the random source is broken', () => {
+      const original = Object.getOwnPropertyDescriptor(globalThis, 'crypto')
+      Object.defineProperty(globalThis, 'crypto', {
+        value: { getRandomValues: (array: Uint8Array) => array.fill(0) },
+        configurable: true,
+      })
+      try {
+        // The server zeroes ids it can't use, so an all-zero id would be stored
+        // and silently orphaned rather than rejected.
+        expect(newTraceId()).not.toBe('0'.repeat(32))
+        expect(newSpanId()).not.toBe('0'.repeat(16))
+      } finally {
+        if (original) {
+          Object.defineProperty(globalThis, 'crypto', original)
+        }
+      }
+    })
+  })
+
+  describe('validation', () => {
+    it.each([
+      ['a valid trace id', '4bf92f3577b34da6a3ce929d0e0e4736', true],
+      ['an all-zero trace id', '0'.repeat(32), false],
+      ['a short trace id', 'abc', false],
+      ['uppercase hex', '4BF92F3577B34DA6A3CE929D0E0E4736', false],
+      ['a non-hex string', 'zzf92f3577b34da6a3ce929d0e0e4736', false],
+      ['a non-string', 12345, false],
+    ])('isValidTraceId rejects/accepts %s', (_name, value, expected) => {
+      expect(isValidTraceId(value)).toBe(expected)
+    })
+
+    it.each([
+      ['a valid span id', '00f067aa0ba902b7', true],
+      ['an all-zero span id', '0'.repeat(16), false],
+      ['a trace-length id', '4bf92f3577b34da6a3ce929d0e0e4736', false],
+    ])('isValidSpanId rejects/accepts %s', (_name, value, expected) => {
+      expect(isValidSpanId(value)).toBe(expected)
+    })
+  })
+})

package/node_modules/@posthog/core/src/traces/ids.ts

@@ -0,0 +1,75 @@
+// W3C Trace Context identifier generation. Trace ids are 16 bytes, span ids 8,
+// both lowercase hex on the JSON wire. The ingestion service *zeroes* ids that
+// aren't exactly the right length rather than rejecting them, silently orphaning
+// the span — so length is load-bearing and every id is validated before it ships.
+
+const TRACE_ID_BYTES = 16
+const SPAN_ID_BYTES = 8
+
+const TRACE_ID_HEX = TRACE_ID_BYTES * 2
+const SPAN_ID_HEX = SPAN_ID_BYTES * 2
+
+const INVALID_TRACE_ID = '0'.repeat(TRACE_ID_HEX)
+const INVALID_SPAN_ID = '0'.repeat(SPAN_ID_HEX)
+
+const HEX_RE = /^[0-9a-f]+$/
+
+type CryptoLike = { getRandomValues?: (array: Uint8Array) => Uint8Array }
+
+/**
+ * Random bytes from the platform's CSPRNG, falling back to `Math.random`.
+ *
+ * The fallback exists for React Native, which has no global `crypto` without a
+ * polyfill. Trace ids need collision resistance, not unpredictability.
+ */
+export function getRandomBytes(byteLength: number): Uint8Array {
+  const bytes = new Uint8Array(byteLength)
+  const cryptoLike = (globalThis as { crypto?: CryptoLike }).crypto
+  if (cryptoLike && typeof cryptoLike.getRandomValues === 'function') {
+    try {
+      cryptoLike.getRandomValues(bytes)
+      return bytes
+    } catch {
+      // A locked-down `crypto` throws; fall through to the `Math.random` path.
+    }
+  }
+  for (let i = 0; i < byteLength; i++) {
+    bytes[i] = Math.floor(Math.random() * 256)
+  }
+  return bytes
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+function randomHexId(byteLength: number): string {
+  const hex = bytesToHex(getRandomBytes(byteLength))
+  // An all-zero id is invalid per W3C and the server treats one as absent, so the
+  // span would be stored and silently orphaned. Only reachable from a broken source.
+  return /[^0]/.test(hex) ? hex : hex.slice(0, -1) + '1'
+}
+
+export function newTraceId(): string {
+  return randomHexId(TRACE_ID_BYTES)
+}
+
+export function newSpanId(): string {
+  return randomHexId(SPAN_ID_BYTES)
+}
+
+function isValidHexId(value: unknown, length: number, invalid: string): value is string {
+  return typeof value === 'string' && value.length === length && value !== invalid && HEX_RE.test(value)
+}
+
+export function isValidTraceId(value: unknown): value is string {
+  return isValidHexId(value, TRACE_ID_HEX, INVALID_TRACE_ID)
+}
+
+export function isValidSpanId(value: unknown): value is string {
+  return isValidHexId(value, SPAN_ID_HEX, INVALID_SPAN_ID)
+}