@open-mercato/telemetry 0.6.7-develop.6834.1.e76f4b8cbc

package/src/__tests__/otlp-integration.test.ts

@@ -0,0 +1,264 @@
+/**
+ * The real OtlpProvider wired to in-memory OTEL exporters (no network,
+ * deterministic). Proves the OTEL-specific behaviour our design relies on:
+ * span shape, the delegation/nesting model, cross-boundary trace propagation
+ * (same traceId), root-per-request, log correlation, and metrics.
+ */
+import { SpanStatusCode, propagation, trace, context, ROOT_CONTEXT } from '@opentelemetry/api'
+import { InMemorySpanExporter, SimpleSpanProcessor, type ReadableSpan } from '@opentelemetry/sdk-trace-base'
+import { InMemoryLogRecordExporter, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs'
+import { InMemoryMetricExporter, PeriodicExportingMetricReader, AggregationTemporality } from '@opentelemetry/sdk-metrics'
+
+import { OtlpProvider } from '../provider/otlp-provider'
+import {
+  createLogger,
+  resetLoggerExtension,
+  resetLoggerRegistry,
+} from '@open-mercato/shared/lib/logger'
+import { setActiveProvider, resetActiveProvider } from '../provider/registry'
+import { resetTelemetryEnvCache } from '../env'
+import { registerTelemetryLogger } from '../facade/logger-bridge'
+import { withSpan, captureTraceContext, continueTrace, reportError, counter } from '../index'
+
+const spanExporter = new InMemorySpanExporter()
+const logExporter = new InMemoryLogRecordExporter()
+const metricExporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE)
+const metricReader = new PeriodicExportingMetricReader({ exporter: metricExporter })
+
+let provider: OtlpProvider
+let disposeLogger: (() => void) | undefined
+const logger = createLogger('telemetry-test')
+
+function parentSpanId(span: ReadableSpan): string | undefined {
+  const s = span as { parentSpanContext?: { spanId?: string }; parentSpanId?: string }
+  return s.parentSpanContext?.spanId ?? s.parentSpanId
+}
+
+beforeAll(async () => {
+  process.env.TELEMETRY_BACKEND = 'otlp'
+  resetTelemetryEnvCache()
+  provider = new OtlpProvider({
+    spanProcessors: [new SimpleSpanProcessor(spanExporter)],
+    logRecordProcessors: [new SimpleLogRecordProcessor({ exporter: logExporter })],
+    metricReaders: [metricReader],
+    instrumentations: [], // pure facade behaviour — pg/undici patching is OTEL's own code
+  })
+  await provider.start()
+  setActiveProvider(provider)
+  disposeLogger = registerTelemetryLogger(provider)
+  // The first span after NodeSDK.start() can be dropped while the global tracer
+  // provider finishes installing — warm it up, settle a tick, then reset.
+  withSpan('warmup', () => undefined)
+  await new Promise((resolve) => setTimeout(resolve, 10))
+  spanExporter.reset()
+})
+
+afterEach(() => {
+  spanExporter.reset()
+  logExporter.reset()
+  metricExporter.reset()
+  delete process.env.TELEMETRY_TRUST_INBOUND_TRACE
+  resetTelemetryEnvCache()
+})
+
+afterAll(async () => {
+  await provider.shutdown()
+  disposeLogger?.()
+  resetLoggerExtension()
+  resetLoggerRegistry()
+  resetActiveProvider()
+  delete process.env.TELEMETRY_BACKEND
+  resetTelemetryEnvCache()
+})
+
+describe('OtlpProvider (in-memory exporters)', () => {
+  it('records span name, attributes (dropping undefined), and ok status', () => {
+    withSpan('op', (s) => s.setAttribute('x', 1), { attributes: { a: 'b', skip: undefined } })
+    const span = spanExporter.getFinishedSpans().find((s) => s.name === 'op')
+    expect(span).toBeDefined()
+    expect(span?.attributes.a).toBe('b')
+    expect(span?.attributes.x).toBe(1)
+    expect(span?.attributes).not.toHaveProperty('skip')
+    expect(span?.status.code).toBe(SpanStatusCode.UNSET)
+  })
+
+  it('records exceptions + error status on a span', () => {
+    withSpan('boom', (s) => {
+      s.recordException(new Error('kaboom'))
+      s.setStatus('error', 'failed')
+    })
+    const span = spanExporter.getFinishedSpans().find((s) => s.name === 'boom')
+    expect(span?.status.code).toBe(SpanStatusCode.ERROR)
+    expect(span?.events.some((e) => e.name === 'exception')).toBe(true)
+  })
+
+  it('nests child spans under the parent (delegation model)', () => {
+    withSpan('parent', () => withSpan('child', () => undefined))
+    const spans = spanExporter.getFinishedSpans()
+    const parent = spans.find((s) => s.name === 'parent')
+    const child = spans.find((s) => s.name === 'child')
+    expect(parent && child).toBeTruthy()
+    expect(child?.spanContext().traceId).toBe(parent?.spanContext().traceId)
+    expect(parentSpanId(child as ReadableSpan)).toBe(parent?.spanContext().spanId)
+  })
+
+  it('inject() writes a valid W3C traceparent inside an active span', () => {
+    let carrier: Record<string, string> = {}
+    withSpan('producer', () => {
+      carrier = captureTraceContext()
+    })
+    expect(carrier.traceparent).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/)
+  })
+
+  it('propagates trace context across a boundary: consumer shares the producer traceId', () => {
+    let carrier: Record<string, string> = {}
+    withSpan('producer', () => {
+      carrier = captureTraceContext()
+    })
+    const producer = spanExporter.getFinishedSpans().find((s) => s.name === 'producer')
+    const producerTraceId = producer?.spanContext().traceId ?? ''
+    const producerSpanId = producer?.spanContext().spanId ?? ''
+
+    continueTrace(carrier, 'consumer', () => undefined)
+    const consumer = spanExporter.getFinishedSpans().find((s) => s.name === 'consumer')
+
+    expect(producerTraceId).toMatch(/^[0-9a-f]{32}$/)
+    expect(consumer?.spanContext().traceId).toBe(producerTraceId)
+    expect(parentSpanId(consumer as ReadableSpan)).toBe(producerSpanId)
+  })
+
+  it('roots per request: the global propagator drops inbound HTTP context while the queue carrier still propagates', () => {
+    // A carrier as if a load balancer injected an upstream traceparent.
+    let carrier: Record<string, string> = {}
+    withSpan('upstream', () => {
+      carrier = captureTraceContext()
+    })
+    const upstreamTraceId = carrier.traceparent.split('-')[1]
+
+    // Incoming HTTP uses the GLOBAL propagator — it must IGNORE the inbound
+    // context so the request span becomes a fresh root (not a child of the LB).
+    const extracted = propagation.extract(ROOT_CONTEXT, carrier)
+    expect(trace.getSpanContext(extracted)).toBeUndefined()
+
+    // Queue path uses the dedicated propagator — it must STILL honor the carrier.
+    continueTrace(carrier, 'consumer', () => undefined)
+    const consumer = spanExporter.getFinishedSpans().find((s) => s.name === 'consumer')
+    expect(consumer?.spanContext().traceId).toBe(upstreamTraceId)
+  })
+
+  it('global inject writes a backup x-original-traceparent that mirrors traceparent', () => {
+    const carrier: Record<string, string> = {}
+    withSpan('producer', () => {
+      propagation.inject(context.active(), carrier)
+    })
+    expect(carrier.traceparent).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/)
+    expect(carrier['x-original-traceparent']).toBe(carrier.traceparent)
+  })
+
+  it('global extract rejects a caller-supplied backup header by default', () => {
+    const carrier: Record<string, string> = {}
+    withSpan('producer', () => {
+      propagation.inject(context.active(), carrier)
+    })
+    // Simulate the load balancer rewriting `traceparent` to its own (unexported) span.
+    carrier.traceparent = `00-${'a'.repeat(32)}-${'b'.repeat(16)}-01`
+
+    const extracted = propagation.extract(ROOT_CONTEXT, carrier)
+    expect(trace.getSpanContext(extracted)).toBeUndefined()
+  })
+
+  it('global extract trusts the backup header only after explicit opt-in', () => {
+    const carrier: Record<string, string> = {}
+    withSpan('producer', () => {
+      propagation.inject(context.active(), carrier)
+    })
+    const realTraceId = carrier['x-original-traceparent'].split('-')[1]
+    carrier.traceparent = `00-${'a'.repeat(32)}-${'b'.repeat(16)}-01`
+    process.env.TELEMETRY_TRUST_INBOUND_TRACE = 'true'
+    resetTelemetryEnvCache()
+
+    const extracted = propagation.extract(ROOT_CONTEXT, carrier)
+    expect(trace.getSpanContext(extracted)?.traceId).toBe(realTraceId)
+    expect(trace.getSpanContext(extracted)?.traceId).not.toBe('a'.repeat(32))
+  })
+
+  it('global extract roots on a bare inbound traceparent with no backup (LB on entry)', () => {
+    const carrier = { traceparent: `00-${'a'.repeat(32)}-${'b'.repeat(16)}-01` }
+    const extracted = propagation.extract(ROOT_CONTEXT, carrier)
+    expect(trace.getSpanContext(extracted)).toBeUndefined()
+  })
+
+  it('redacts a leaked email from a span exception (PII backstop at the OTEL boundary)', () => {
+    withSpan('pii-span', (s) => {
+      s.recordException(new Error('no account for jan.kowalski@example.com'))
+    })
+    const span = spanExporter.getFinishedSpans().find((s) => s.name === 'pii-span')
+    const exception = span?.events.find((e) => e.name === 'exception')
+    const message = String(exception?.attributes?.['exception.message'] ?? '')
+    expect(message).toContain('[redacted-email]')
+    expect(message).not.toContain('jan.kowalski@example.com')
+  })
+
+  it('redacts secret span attributes at the OTEL provider boundary', () => {
+    withSpan('secret-span', (span) => {
+      span.setAttributes({
+        token: 'secret-token',
+        note: 'contact jane@example.com',
+        token_count: 12,
+      })
+    })
+    const span = spanExporter.getFinishedSpans().find((item) => item.name === 'secret-span')
+    expect(span?.attributes.token).toBe('[redacted]')
+    expect(span?.attributes.note).toBe('contact [redacted-email]')
+    expect(span?.attributes.token_count).toBe(12)
+  })
+
+  it('emits structured logs and error exceptions through reportError', () => {
+    logger.info('hello', { k: 1 })
+    reportError(new Error('explode'), { module: 'orders' })
+    const records = logExporter.getFinishedLogRecords()
+    const info = records.find((r) => r.body === 'hello')
+    expect(info?.attributes?.k).toBe(1)
+    const err = records.find((r) => r.severityText === 'error')
+    expect(err?.attributes?.['exception.message']).toBe('explode')
+  })
+
+  it('redacts direct provider logs at the final export boundary', () => {
+    provider.emitLog({
+      level: 'warn',
+      message: 'upstream rejected Bearer raw-token',
+      attributes: {
+        token: 'raw-token',
+        note: 'owner@example.com',
+        token_count: 3,
+      },
+    })
+    const record = logExporter.getFinishedLogRecords().find((item) => item.severityText === 'warn')
+    expect(record?.body).toBe('upstream rejected Bearer [redacted]')
+    expect(record?.attributes?.token).toBe('[redacted]')
+    expect(record?.attributes?.note).toBe('[redacted-email]')
+    expect(record?.attributes?.token_count).toBe(3)
+  })
+
+  it('exposes the active trace context for log correlation (undefined when none active)', () => {
+    expect(provider.activeTraceContext()).toBeUndefined()
+    let seen: { traceId: string; spanId: string } | undefined
+    withSpan('logged-op', () => {
+      seen = provider.activeTraceContext()
+    })
+    const span = spanExporter.getFinishedSpans().find((s) => s.name === 'logged-op')
+    expect(seen?.traceId).toMatch(/^[0-9a-f]{32}$/)
+    expect(seen?.spanId).toMatch(/^[0-9a-f]{16}$/)
+    expect(seen?.traceId).toBe(span?.spanContext().traceId)
+    expect(seen?.spanId).toBe(span?.spanContext().spanId)
+  })
+
+  it('records metrics through the OTEL meter', async () => {
+    counter('om.errors', 1, { module: 'orders' })
+    await metricReader.forceFlush()
+    const metricNames = metricExporter
+      .getMetrics()
+      .flatMap((rm) => rm.scopeMetrics.flatMap((sm) => sm.metrics.map((m) => m.descriptor.name)))
+    expect(metricNames).toContain('om.errors')
+  })
+})

package/src/__tests__/pg-instrumentation.test.ts

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Guards that an OTLP-backed telemetry provider actually instruments `pg`, so a
+ * database query emits a span. This is the capability that makes worker/scheduler
+ * DB work visible (the `queue worker` bootstrap in `@open-mercato/cli` initializes
+ * telemetry BEFORE it loads MikroORM's Postgres driver precisely so these spans
+ * are captured — see packages/cli/src/bin.ts).
+ *
+ * It runs in a real child Node process rather than in-process: OpenTelemetry's
+ * pg instrumentation patches `pg` via require-in-the-middle, which jest's module
+ * system does not exercise faithfully (the sibling otlp-integration.test.ts wires
+ * `instrumentations: []` for that reason). No database is needed — a connection to
+ * a dead port still drives the query path, and the instrumentation records the
+ * span before the underlying call fails.
+ */
+const distProvider = path.resolve(__dirname, '../../dist/provider/otlp-provider.js')
+const pkgRoot = path.resolve(__dirname, '../..')
+
+const CHILD_SCRIPT = `
+const { OtlpProvider } = await import('@open-mercato/telemetry/provider/otlp-provider')
+const { setActiveProvider } = await import('@open-mercato/telemetry/provider/registry')
+const { InMemorySpanExporter, SimpleSpanProcessor } = await import('@opentelemetry/sdk-trace-base')
+
+// No 'instrumentations' override: the provider's DEFAULT list must include the
+// pg instrumentation (with PII-safe options), or this probe records no span.
+const exporter = new InMemorySpanExporter()
+const provider = new OtlpProvider({
+  spanProcessors: [new SimpleSpanProcessor(exporter)],
+})
+// start() BEFORE pg is imported — the ordering the CLI bootstrap guarantees.
+await provider.start()
+setActiveProvider(provider)
+
+const pgModule = await import('pg')
+const Client = (pgModule.default ?? pgModule).Client
+const client = new Client({ host: '127.0.0.1', port: 1, connectionTimeoutMillis: 200 })
+try { await client.connect() } catch {}
+try { await client.query('SELECT $1::text', ['pii-sentinel-value']) } catch {}
+await new Promise((resolve) => setTimeout(resolve, 250))
+const spans = exporter.getFinishedSpans().map((s) => ({ name: s.name, attributes: s.attributes }))
+console.log('SPANS=' + JSON.stringify(spans))
+process.exit(0)
+`
+
+type ProbeSpan = { name: string; attributes: Record<string, unknown> }
+
+function runChild(): ProbeSpan[] {
+  // The script must live inside the package tree: ESM resolves bare specifiers
+  // (`@open-mercato/telemetry`, `@opentelemetry/*`, `pg`) relative to the file's
+  // location, not the process cwd.
+  const scriptFile = path.join(pkgRoot, `.pg-instrumentation-probe.${process.pid}.mjs`)
+  fs.writeFileSync(scriptFile, CHILD_SCRIPT)
+  try {
+    const result = spawnSync(process.execPath, [scriptFile], {
+      cwd: pkgRoot,
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        TELEMETRY_BACKEND: 'otlp',
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://127.0.0.1:1',
+        OM_LOG_LEVEL: 'error',
+      },
+      timeout: 30_000,
+    })
+    const line = (result.stdout || '').split('\n').find((l) => l.startsWith('SPANS='))
+    if (!line) throw new Error(`child produced no SPANS output.\nstdout: ${result.stdout}\nstderr: ${result.stderr}`)
+    return JSON.parse(line.slice('SPANS='.length)) as ProbeSpan[]
+  } finally {
+    fs.rmSync(scriptFile, { force: true })
+  }
+}
+
+// The build output must exist (the child imports the compiled provider). Runs in
+// CI after build:packages; skip locally when the package hasn't been built yet.
+const maybe = fs.existsSync(distProvider) ? describe : describe.skip
+
+maybe('OTLP provider pg instrumentation', () => {
+  it('emits a pg query span (default instrumentations) without leaking bound parameter values', () => {
+    const spans = runChild()
+    expect(spans.some((span) => span.name.startsWith('pg.query'))).toBe(true)
+    // enhancedDatabaseReporting must stay off in the provider's default wiring:
+    // the statement text may appear, bound values must not.
+    expect(JSON.stringify(spans)).not.toContain('pii-sentinel-value')
+  }, 35_000)
+})

package/src/__tests__/pg-pii-config.test.ts

@@ -0,0 +1,14 @@
+import { PG_INSTRUMENTATION_OPTIONS } from '../provider/otlp-provider'
+
+/**
+ * Regression guard for the PII promise (telemetry spec Privacy / R12): the pg
+ * instrumentation must never capture bound SQL parameter VALUES. Flipping this
+ * to `true` would leak user data into `db.statement` spans. The runtime
+ * behaviour itself is OpenTelemetry's (tested upstream); this locks OUR
+ * configuration so a refactor can't silently enable it.
+ */
+describe('pg instrumentation PII config', () => {
+  it('never enables enhancedDatabaseReporting (no SQL parameter values in spans)', () => {
+    expect(PG_INSTRUMENTATION_OPTIONS.enhancedDatabaseReporting).toBe(false)
+  })
+})

package/src/__tests__/redact.test.ts

@@ -0,0 +1,92 @@
+import { redactPii, redactAttributes } from '../facade/redact'
+
+describe('redactPii', () => {
+  it('masks email addresses', () => {
+    expect(redactPii('no user for jan.kowalski@example.com found')).toBe(
+      'no user for [redacted-email] found',
+    )
+  })
+
+  it('masks every email in the text', () => {
+    expect(redactPii('a@b.co and c.d+tag@sub.example.org')).toBe(
+      '[redacted-email] and [redacted-email]',
+    )
+  })
+
+  it('handles hostile runs of email punctuation without pathological matching', () => {
+    const hostile = `${'%'.repeat(100_000)} not-an-email`
+
+    expect(redactPii(hostile)).toBe(hostile)
+  })
+
+  it('masks an Authorization header dump (scheme + token) in one pass', () => {
+    expect(redactPii('request failed: Authorization: Bearer eyJhbGci.abc-123_x')).toBe(
+      'request failed: Authorization: [redacted]',
+    )
+  })
+
+  it('masks a standalone Bearer/Basic/ApiKey token in text', () => {
+    expect(redactPii('used Basic dXNlcjpwYXNz to auth')).toBe('used Basic [redacted] to auth')
+    expect(redactPii('sent ApiKey sk_live_abc123 upstream')).toBe('sent ApiKey [redacted] upstream')
+  })
+
+  it('masks a cookie header dump but keeps surrounding structure', () => {
+    expect(redactPii("headers { cookie: 'session=abc123'; x-id: 5 }")).toBe(
+      "headers { cookie: [redacted]; x-id: 5 }",
+    )
+  })
+
+  it('leaves opaque ids/UUIDs untouched (we keep those)', () => {
+    const uuid = '3f2504e0-4f89-41d3-9a0c-0305e82c3301'
+    expect(redactPii(`tenant ${uuid}`)).toBe(`tenant ${uuid}`)
+  })
+
+  it('is a no-op for text with no PII', () => {
+    expect(redactPii('connection refused')).toBe('connection refused')
+  })
+})
+
+describe('redactAttributes', () => {
+  it('masks values under secret-looking keys', () => {
+    expect(
+      redactAttributes({
+        authorization: 'Bearer secret-token',
+        'set-cookie': 'session=abc',
+        client_secret: 'sk_live_123',
+        'x-api-key': 'key_123',
+        access_token: 'at_123',
+        token: 'generic-token',
+      }),
+    ).toEqual({
+      authorization: '[redacted]',
+      'set-cookie': '[redacted]',
+      client_secret: '[redacted]',
+      'x-api-key': '[redacted]',
+      access_token: '[redacted]',
+      token: '[redacted]',
+    })
+  })
+
+  it('keeps opaque ids and benign fields, and does not clobber token_count', () => {
+    expect(
+      redactAttributes({
+        'om.tenant_id': '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
+        'http.route': '/api/orders',
+        token_count: 42,
+        'http.response.status_code': 500,
+      }),
+    ).toEqual({
+      'om.tenant_id': '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
+      'http.route': '/api/orders',
+      token_count: 42,
+      'http.response.status_code': 500,
+    })
+  })
+
+  it('runs redactPii over non-secret string values (inline email)', () => {
+    expect(redactAttributes({ note: 'contact jan@example.com', module: 'orders' })).toEqual({
+      note: 'contact [redacted-email]',
+      module: 'orders',
+    })
+  })
+})

package/src/__tests__/registry.test.ts

@@ -0,0 +1,77 @@
+import {
+  getActiveProvider,
+  setActiveProvider,
+  resetActiveProvider,
+  registerProvider,
+  getRegisteredProvider,
+} from '../provider/registry'
+import type { Span, TelemetryProvider } from '../types'
+
+// The provider registry stores state on this global symbol (see registry.ts).
+// It is load-bearing: the worker bootstrap esbuild-bundles a PRIVATE copy of the
+// telemetry module while job handlers load the SOURCE copy, and only a global
+// (not module-local) singleton lets those copies share one active provider.
+const GLOBAL_KEY = Symbol.for('@open-mercato/telemetry.providerRegistry')
+
+function fakeProvider(name: string): TelemetryProvider {
+  return {
+    name,
+    supports: [],
+    async start() {},
+    async shutdown() {},
+    runInSpan: (_n, _o, fn) => fn({} as Span),
+    activeSpan: () => undefined,
+    activeTraceContext: () => undefined,
+    inject: () => {},
+    runInRemoteSpan: (_c, _n, _o, fn) => fn({} as Span),
+    emitLog: () => {},
+    recordMetric: () => {},
+  }
+}
+
+afterEach(() => {
+  resetActiveProvider()
+})
+
+describe('provider registry (global singleton)', () => {
+  it('defaults to a noop provider', () => {
+    expect(getActiveProvider().name).toBe('noop')
+  })
+
+  it('stores the active provider on globalThis, not in module-local state', () => {
+    const p = fakeProvider('otlp')
+    setActiveProvider(p)
+    const store = (globalThis as Record<symbol, { active: TelemetryProvider } | undefined>)[GLOBAL_KEY]
+    expect(store?.active).toBe(p)
+    expect(getActiveProvider()).toBe(p)
+  })
+
+  it('shares the active provider across a separately-loaded module copy (dual-copy guard)', () => {
+    const p = fakeProvider('otlp')
+    setActiveProvider(p)
+    // A second, isolated copy of the registry module — its own module closure,
+    // mimicking the worker's bundled-DI vs source-handler copies. With a global
+    // singleton it resolves the SAME provider; with module-local state it would
+    // see its own fresh noop default and this would fail.
+    let copyActive: TelemetryProvider | undefined
+    jest.isolateModules(() => {
+      copyActive = (require('../provider/registry') as typeof import('../provider/registry')).getActiveProvider()
+    })
+    expect(copyActive).toBe(p)
+  })
+
+  it('registerProvider / getRegisteredProvider round-trips by name', () => {
+    const p = fakeProvider('otlp')
+    registerProvider(p)
+    expect(getRegisteredProvider('otlp')).toBe(p)
+    expect(getRegisteredProvider('nope')).toBeUndefined()
+  })
+
+  it('resetActiveProvider restores the noop default and clears registrations', () => {
+    setActiveProvider(fakeProvider('otlp'))
+    registerProvider(fakeProvider('newrelic'))
+    resetActiveProvider()
+    expect(getActiveProvider().name).toBe('noop')
+    expect(getRegisteredProvider('newrelic')).toBeUndefined()
+  })
+})

package/src/__tests__/run-span.test.ts

@@ -0,0 +1,56 @@
+import { runSpan } from '../provider/run-span'
+import type { Span } from '../types'
+
+function fakeSpan() {
+  const calls = { exceptions: [] as unknown[], status: '' as string, ended: 0 }
+  const span: Span = {
+    setAttribute() {},
+    setAttributes() {},
+    recordException: (e) => calls.exceptions.push(e),
+    setStatus: (s) => {
+      calls.status = s
+    },
+    end: () => {
+      calls.ended += 1
+    },
+  }
+  return { span, calls }
+}
+
+describe('runSpan (sync + async lifecycle)', () => {
+  it('ends the span and returns the value for a sync function', () => {
+    const { span, calls } = fakeSpan()
+    expect(runSpan(span, () => 5)).toBe(5)
+    expect(calls.ended).toBe(1)
+    expect(calls.status).toBe('')
+  })
+
+  it('records the exception, ends, and rethrows on a sync throw', () => {
+    const { span, calls } = fakeSpan()
+    const err = new Error('sync')
+    expect(() => runSpan(span, () => { throw err })).toThrow('sync')
+    expect(calls.exceptions).toEqual([err])
+    expect(calls.status).toBe('error')
+    expect(calls.ended).toBe(1)
+  })
+
+  it('ends the span only after an async function resolves', async () => {
+    const { span, calls } = fakeSpan()
+    const p = runSpan(span, async () => {
+      expect(calls.ended).toBe(0)
+      return 'ok'
+    })
+    expect(calls.ended).toBe(0) // not ended synchronously
+    await expect(p).resolves.toBe('ok')
+    expect(calls.ended).toBe(1)
+  })
+
+  it('records the exception, ends, and rejects on an async rejection', async () => {
+    const { span, calls } = fakeSpan()
+    const err = new Error('async')
+    await expect(runSpan(span, async () => { throw err })).rejects.toThrow('async')
+    expect(calls.exceptions).toEqual([err])
+    expect(calls.status).toBe('error')
+    expect(calls.ended).toBe(1)
+  })
+})

package/src/__tests__/serialize.test.ts

@@ -0,0 +1,47 @@
+import { serializeError } from '../facade/serialize'
+
+describe('serializeError (PII-safe)', () => {
+  it('keeps name, message, and stack for an Error', () => {
+    const err = new TypeError('bad thing')
+    const out = serializeError(err)
+    expect(out.name).toBe('TypeError')
+    expect(out.message).toBe('bad thing')
+    expect(out.stack).toContain('bad thing')
+  })
+
+  it('folds the cause chain into the message (names/messages only)', () => {
+    const root = new Error('db down')
+    const wrapped = new Error('save failed', { cause: root })
+    const out = serializeError(wrapped)
+    expect(out.message).toBe('save failed — caused by Error: db down')
+  })
+
+  it('does not leak arbitrary error properties (e.g. request bodies)', () => {
+    const err = Object.assign(new Error('boom'), { requestBody: { secret: 'SECRET' } })
+    const out = serializeError(err)
+    expect(JSON.stringify(out)).not.toContain('SECRET')
+    expect(out).not.toHaveProperty('requestBody')
+  })
+
+  it('handles circular causes without infinite recursion', () => {
+    const a = new Error('a') as Error & { cause?: unknown }
+    const b = new Error('b', { cause: a })
+    a.cause = b
+    expect(() => serializeError(b)).not.toThrow()
+  })
+
+  it('handles non-Error values', () => {
+    expect(serializeError('plain string')).toMatchObject({ name: 'NonError', message: 'plain string' })
+    expect(serializeError({ password: 'SECRET', body: { email: 'person@example.com' } })).toEqual({
+      name: 'NonError',
+      message: '[non-error object]',
+    })
+  })
+
+  it('redacts a leaked email from message and stack (Privacy backstop)', () => {
+    const err = new Error('no account for jan.kowalski@example.com')
+    const out = serializeError(err)
+    expect(out.message).toBe('no account for [redacted-email]')
+    expect(out.stack).not.toContain('jan.kowalski@example.com')
+  })
+})