@peac/telemetry 0.9.31

package/tests/attributes.test.ts

@@ -0,0 +1,126 @@
+/**
+ * @peac/telemetry - Attribute constants tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  PEAC_ATTRS,
+  PEAC_EVENTS,
+  PEAC_METRICS,
+  TRACE_CONTEXT_EXTENSIONS,
+} from '../src/attributes.js';
+
+describe('PEAC_ATTRS', () => {
+  it('should define core attributes', () => {
+    expect(PEAC_ATTRS.VERSION).toBe('peac.version');
+    expect(PEAC_ATTRS.EVENT).toBe('peac.event');
+    expect(PEAC_ATTRS.RECEIPT_HASH).toBe('peac.receipt.hash');
+    expect(PEAC_ATTRS.POLICY_HASH).toBe('peac.policy.hash');
+    expect(PEAC_ATTRS.DECISION).toBe('peac.decision');
+    expect(PEAC_ATTRS.REASON_CODE).toBe('peac.reason_code');
+    expect(PEAC_ATTRS.ISSUER).toBe('peac.issuer');
+    expect(PEAC_ATTRS.ISSUER_HASH).toBe('peac.issuer_hash');
+    expect(PEAC_ATTRS.KID).toBe('peac.kid');
+    expect(PEAC_ATTRS.VALID).toBe('peac.valid');
+  });
+
+  it('should use stable OTel semconv for HTTP', () => {
+    // These are stable OTel semantic conventions
+    expect(PEAC_ATTRS.HTTP_METHOD).toBe('http.request.method');
+    expect(PEAC_ATTRS.HTTP_PATH).toBe('url.path');
+  });
+
+  it('should define HTTP hash attributes', () => {
+    expect(PEAC_ATTRS.HTTP_HOST_HASH).toBe('peac.http.host_hash');
+    expect(PEAC_ATTRS.HTTP_CLIENT_HASH).toBe('peac.http.client_hash');
+  });
+
+  it('should define payment attributes', () => {
+    expect(PEAC_ATTRS.PAYMENT_RAIL).toBe('peac.payment.rail');
+    expect(PEAC_ATTRS.PAYMENT_AMOUNT).toBe('peac.payment.amount');
+    expect(PEAC_ATTRS.PAYMENT_CURRENCY).toBe('peac.payment.currency');
+  });
+
+  it('should define duration attribute', () => {
+    expect(PEAC_ATTRS.DURATION_MS).toBe('peac.duration_ms');
+  });
+
+  it('should be readonly (const assertion)', () => {
+    // TypeScript ensures this at compile time
+    // Runtime test: object should be frozen-like
+    const keys = Object.keys(PEAC_ATTRS);
+    expect(keys.length).toBeGreaterThan(0);
+
+    // All values should be strings
+    for (const key of keys) {
+      expect(typeof PEAC_ATTRS[key as keyof typeof PEAC_ATTRS]).toBe('string');
+    }
+  });
+
+  it('should use peac. prefix consistently', () => {
+    const peacPrefixed = Object.values(PEAC_ATTRS).filter((v) => v.startsWith('peac.'));
+    const otherPrefixed = Object.values(PEAC_ATTRS).filter((v) => !v.startsWith('peac.'));
+
+    // Most should be peac. prefixed
+    expect(peacPrefixed.length).toBeGreaterThan(otherPrefixed.length);
+
+    // HTTP should use standard OTel conventions
+    expect(otherPrefixed).toContain('http.request.method');
+    expect(otherPrefixed).toContain('url.path');
+  });
+});
+
+describe('PEAC_EVENTS', () => {
+  it('should define all event names', () => {
+    expect(PEAC_EVENTS.RECEIPT_ISSUED).toBe('peac.receipt.issued');
+    expect(PEAC_EVENTS.RECEIPT_VERIFIED).toBe('peac.receipt.verified');
+    expect(PEAC_EVENTS.ACCESS_DECISION).toBe('peac.access.decision');
+  });
+
+  it('should use peac. prefix', () => {
+    for (const event of Object.values(PEAC_EVENTS)) {
+      expect(event.startsWith('peac.')).toBe(true);
+    }
+  });
+});
+
+describe('PEAC_METRICS', () => {
+  it('should define counter metrics', () => {
+    expect(PEAC_METRICS.RECEIPTS_ISSUED).toBe('peac.receipts.issued');
+    expect(PEAC_METRICS.RECEIPTS_VERIFIED).toBe('peac.receipts.verified');
+    expect(PEAC_METRICS.ACCESS_DECISIONS).toBe('peac.access.decisions');
+  });
+
+  it('should define histogram metrics', () => {
+    expect(PEAC_METRICS.ISSUE_DURATION).toBe('peac.issue.duration');
+    expect(PEAC_METRICS.VERIFY_DURATION).toBe('peac.verify.duration');
+  });
+
+  it('should use peac. prefix', () => {
+    for (const metric of Object.values(PEAC_METRICS)) {
+      expect(metric.startsWith('peac.')).toBe(true);
+    }
+  });
+});
+
+describe('TRACE_CONTEXT_EXTENSIONS', () => {
+  it('should use w3c/ namespace (vendor-neutral)', () => {
+    expect(TRACE_CONTEXT_EXTENSIONS.TRACEPARENT).toBe('w3c/traceparent');
+    expect(TRACE_CONTEXT_EXTENSIONS.TRACESTATE).toBe('w3c/tracestate');
+  });
+
+  it('should match extension key pattern', () => {
+    // Pattern: ^[a-z0-9_.-]+/[a-z0-9_.-]+$
+    const pattern = /^[a-z0-9_.-]+\/[a-z0-9_.-]+$/;
+
+    expect(pattern.test(TRACE_CONTEXT_EXTENSIONS.TRACEPARENT)).toBe(true);
+    expect(pattern.test(TRACE_CONTEXT_EXTENSIONS.TRACESTATE)).toBe(true);
+  });
+
+  it('should NOT use io.opentelemetry namespace', () => {
+    // Vendor-neutral: w3c/ not io.opentelemetry/
+    for (const key of Object.values(TRACE_CONTEXT_EXTENSIONS)) {
+      expect(key.startsWith('io.opentelemetry')).toBe(false);
+    }
+  });
+});

package/tests/noop.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @peac/telemetry - No-op provider tests
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { noopProvider } from '../src/noop.js';
+import type { TelemetryProvider } from '../src/types.js';
+
+describe('noopProvider', () => {
+  it('should implement TelemetryProvider interface', () => {
+    const provider: TelemetryProvider = noopProvider;
+
+    expect(typeof provider.onReceiptIssued).toBe('function');
+    expect(typeof provider.onReceiptVerified).toBe('function');
+    expect(typeof provider.onAccessDecision).toBe('function');
+  });
+
+  it('should not throw on onReceiptIssued', () => {
+    expect(() =>
+      noopProvider.onReceiptIssued({
+        receiptHash: 'sha256:test',
+      })
+    ).not.toThrow();
+  });
+
+  it('should not throw on onReceiptVerified', () => {
+    expect(() =>
+      noopProvider.onReceiptVerified({
+        receiptHash: 'sha256:test',
+        valid: true,
+      })
+    ).not.toThrow();
+  });
+
+  it('should not throw on onAccessDecision', () => {
+    expect(() =>
+      noopProvider.onAccessDecision({
+        decision: 'allow',
+      })
+    ).not.toThrow();
+  });
+
+  it('should return undefined from all methods', () => {
+    const issued = noopProvider.onReceiptIssued({
+      receiptHash: 'sha256:test',
+    });
+    const verified = noopProvider.onReceiptVerified({
+      receiptHash: 'sha256:test',
+      valid: true,
+    });
+    const decision = noopProvider.onAccessDecision({
+      decision: 'allow',
+    });
+
+    expect(issued).toBeUndefined();
+    expect(verified).toBeUndefined();
+    expect(decision).toBeUndefined();
+  });
+
+  it('should handle complex input without errors', () => {
+    expect(() =>
+      noopProvider.onReceiptIssued({
+        receiptHash: 'sha256:complex',
+        policyHash: 'sha256:policy',
+        issuer: 'https://api.example.com',
+        kid: '2025-01-01T00:00:00Z',
+        http: { method: 'POST', path: '/api/v1/resource' },
+        durationMs: 150,
+      })
+    ).not.toThrow();
+
+    expect(() =>
+      noopProvider.onReceiptVerified({
+        receiptHash: 'sha256:complex',
+        issuer: 'https://api.example.com',
+        kid: '2025-01-01',
+        valid: false,
+        reasonCode: 'SIGNATURE_INVALID',
+        http: { method: 'GET', path: '/verify' },
+        durationMs: 25,
+      })
+    ).not.toThrow();
+
+    expect(() =>
+      noopProvider.onAccessDecision({
+        receiptHash: 'sha256:complex',
+        policyHash: 'sha256:policy',
+        decision: 'deny',
+        reasonCode: 'INSUFFICIENT_PAYMENT',
+        payment: { rail: 'stripe', amount: 500, currency: 'USD' },
+        http: { method: 'POST', path: '/protected' },
+      })
+    ).not.toThrow();
+  });
+
+  it('should be usable as default provider', () => {
+    // Simulate setting as default
+    let currentProvider: TelemetryProvider | undefined = noopProvider;
+
+    // Should work without errors
+    currentProvider.onReceiptIssued({ receiptHash: 'sha256:test' });
+    currentProvider.onReceiptVerified({ receiptHash: 'sha256:test', valid: true });
+    currentProvider.onAccessDecision({ decision: 'allow' });
+
+    // Should be replaceable
+    currentProvider = undefined;
+    expect(currentProvider).toBeUndefined();
+  });
+});

package/tests/provider.test.ts

@@ -0,0 +1,223 @@
+/**
+ * @peac/telemetry - Provider registry tests
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  providerRef,
+  setTelemetryProvider,
+  getTelemetryProvider,
+  isTelemetryEnabled,
+} from '../src/provider.js';
+import { noopProvider } from '../src/noop.js';
+import type { TelemetryProvider } from '../src/types.js';
+
+describe('providerRef', () => {
+  beforeEach(() => {
+    // Reset provider before each test
+    providerRef.current = undefined;
+  });
+
+  it('should start with undefined (disabled)', () => {
+    expect(providerRef.current).toBeUndefined();
+  });
+
+  it('should allow direct assignment', () => {
+    providerRef.current = noopProvider;
+    expect(providerRef.current).toBe(noopProvider);
+  });
+
+  it('should allow setting to undefined', () => {
+    providerRef.current = noopProvider;
+    providerRef.current = undefined;
+    expect(providerRef.current).toBeUndefined();
+  });
+});
+
+describe('setTelemetryProvider', () => {
+  beforeEach(() => {
+    providerRef.current = undefined;
+  });
+
+  it('should set the provider', () => {
+    setTelemetryProvider(noopProvider);
+    expect(providerRef.current).toBe(noopProvider);
+  });
+
+  it('should allow undefined to disable', () => {
+    setTelemetryProvider(noopProvider);
+    setTelemetryProvider(undefined);
+    expect(providerRef.current).toBeUndefined();
+  });
+
+  it('should be idempotent', () => {
+    setTelemetryProvider(noopProvider);
+    setTelemetryProvider(noopProvider);
+    setTelemetryProvider(noopProvider);
+    expect(providerRef.current).toBe(noopProvider);
+  });
+
+  it('should allow replacing provider', () => {
+    const provider1: TelemetryProvider = {
+      onReceiptIssued: vi.fn(),
+      onReceiptVerified: vi.fn(),
+      onAccessDecision: vi.fn(),
+    };
+
+    const provider2: TelemetryProvider = {
+      onReceiptIssued: vi.fn(),
+      onReceiptVerified: vi.fn(),
+      onAccessDecision: vi.fn(),
+    };
+
+    setTelemetryProvider(provider1);
+    expect(providerRef.current).toBe(provider1);
+
+    setTelemetryProvider(provider2);
+    expect(providerRef.current).toBe(provider2);
+  });
+
+  it('should not throw', () => {
+    expect(() => setTelemetryProvider(noopProvider)).not.toThrow();
+    expect(() => setTelemetryProvider(undefined)).not.toThrow();
+  });
+});
+
+describe('getTelemetryProvider', () => {
+  beforeEach(() => {
+    providerRef.current = undefined;
+  });
+
+  it('should return undefined when no provider set', () => {
+    expect(getTelemetryProvider()).toBeUndefined();
+  });
+
+  it('should return the current provider', () => {
+    setTelemetryProvider(noopProvider);
+    expect(getTelemetryProvider()).toBe(noopProvider);
+  });
+
+  it('should return same value as providerRef.current', () => {
+    setTelemetryProvider(noopProvider);
+    expect(getTelemetryProvider()).toBe(providerRef.current);
+  });
+});
+
+describe('isTelemetryEnabled', () => {
+  beforeEach(() => {
+    providerRef.current = undefined;
+  });
+
+  it('should return false when disabled', () => {
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+
+  it('should return true when provider set', () => {
+    setTelemetryProvider(noopProvider);
+    expect(isTelemetryEnabled()).toBe(true);
+  });
+
+  it('should return false after disabling', () => {
+    setTelemetryProvider(noopProvider);
+    setTelemetryProvider(undefined);
+    expect(isTelemetryEnabled()).toBe(false);
+  });
+});
+
+describe('hot path pattern', () => {
+  beforeEach(() => {
+    providerRef.current = undefined;
+  });
+
+  it('should skip telemetry when disabled', () => {
+    const mockFn = vi.fn();
+
+    // Hot path pattern
+    const p = providerRef.current;
+    if (p) {
+      mockFn();
+    }
+
+    expect(mockFn).not.toHaveBeenCalled();
+  });
+
+  it('should call telemetry when enabled', () => {
+    const mockProvider: TelemetryProvider = {
+      onReceiptIssued: vi.fn(),
+      onReceiptVerified: vi.fn(),
+      onAccessDecision: vi.fn(),
+    };
+
+    setTelemetryProvider(mockProvider);
+
+    // Hot path pattern
+    const p = providerRef.current;
+    if (p) {
+      p.onReceiptIssued({ receiptHash: 'sha256:test' });
+    }
+
+    expect(mockProvider.onReceiptIssued).toHaveBeenCalledWith({
+      receiptHash: 'sha256:test',
+    });
+  });
+
+  it('should guard against throwing providers', () => {
+    const throwingProvider: TelemetryProvider = {
+      onReceiptIssued: () => {
+        throw new Error('Provider error');
+      },
+      onReceiptVerified: vi.fn(),
+      onAccessDecision: vi.fn(),
+    };
+
+    setTelemetryProvider(throwingProvider);
+
+    // Hot path pattern with guard
+    const p = providerRef.current;
+    if (p) {
+      try {
+        p.onReceiptIssued({ receiptHash: 'sha256:test' });
+      } catch {
+        // Telemetry MUST NOT break core flow - swallow silently
+      }
+    }
+
+    // Should not throw, test passes if we get here
+    expect(true).toBe(true);
+  });
+
+  it('should have zero overhead when disabled (structural)', () => {
+    // This test documents the performance contract structurally
+    // When providerRef.current is undefined, no provider methods are called
+    // Time-based assertions are avoided to prevent CI flakes
+
+    const iterations = 1000;
+    let callCount = 0;
+
+    for (let i = 0; i < iterations; i++) {
+      const p = providerRef.current;
+      if (p) {
+        callCount++;
+      }
+    }
+
+    // Structural assertion: no calls when disabled
+    expect(callCount).toBe(0);
+    // The pattern above is the only overhead (single truthiness check)
+  });
+});
+
+describe('concurrent access', () => {
+  beforeEach(() => {
+    providerRef.current = undefined;
+  });
+
+  it('should handle rapid enable/disable', () => {
+    for (let i = 0; i < 100; i++) {
+      setTelemetryProvider(noopProvider);
+      expect(isTelemetryEnabled()).toBe(true);
+      setTelemetryProvider(undefined);
+      expect(isTelemetryEnabled()).toBe(false);
+    }
+  });
+});

package/tests/types.test.ts

@@ -0,0 +1,218 @@
+/**
+ * @peac/telemetry - Type tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+  TelemetryDecision,
+  PrivacyMode,
+  TelemetryConfig,
+  TelemetryProvider,
+  ReceiptIssuedInput,
+  ReceiptVerifiedInput,
+  AccessDecisionInput,
+  HttpContext,
+  PaymentContext,
+} from '../src/types.js';
+
+describe('TelemetryDecision', () => {
+  it('should accept valid decision values', () => {
+    const allow: TelemetryDecision = 'allow';
+    const deny: TelemetryDecision = 'deny';
+    const unknown: TelemetryDecision = 'unknown';
+
+    expect(allow).toBe('allow');
+    expect(deny).toBe('deny');
+    expect(unknown).toBe('unknown');
+  });
+});
+
+describe('PrivacyMode', () => {
+  it('should accept valid privacy mode values', () => {
+    const strict: PrivacyMode = 'strict';
+    const balanced: PrivacyMode = 'balanced';
+    const custom: PrivacyMode = 'custom';
+
+    expect(strict).toBe('strict');
+    expect(balanced).toBe('balanced');
+    expect(custom).toBe('custom');
+  });
+});
+
+describe('TelemetryConfig', () => {
+  it('should require serviceName', () => {
+    const config: TelemetryConfig = {
+      serviceName: 'my-service',
+    };
+
+    expect(config.serviceName).toBe('my-service');
+  });
+
+  it('should accept optional privacy mode', () => {
+    const config: TelemetryConfig = {
+      serviceName: 'my-service',
+      privacyMode: 'strict',
+    };
+
+    expect(config.privacyMode).toBe('strict');
+  });
+
+  it('should accept optional allowlist', () => {
+    const config: TelemetryConfig = {
+      serviceName: 'my-service',
+      privacyMode: 'custom',
+      allowAttributes: ['peac.receipt.hash', 'peac.decision'],
+    };
+
+    expect(config.allowAttributes).toEqual(['peac.receipt.hash', 'peac.decision']);
+  });
+
+  it('should accept optional redaction hook', () => {
+    const redact = (attrs: Record<string, unknown>) => {
+      const result = { ...attrs };
+      delete result['sensitive'];
+      return result;
+    };
+
+    const config: TelemetryConfig = {
+      serviceName: 'my-service',
+      redact,
+    };
+
+    expect(config.redact?.({ sensitive: 'data', safe: 'value' })).toEqual({
+      safe: 'value',
+    });
+  });
+
+  it('should accept enableExperimentalGenAI flag', () => {
+    const config: TelemetryConfig = {
+      serviceName: 'my-service',
+      enableExperimentalGenAI: true,
+    };
+
+    expect(config.enableExperimentalGenAI).toBe(true);
+  });
+});
+
+describe('ReceiptIssuedInput', () => {
+  it('should require receiptHash', () => {
+    const input: ReceiptIssuedInput = {
+      receiptHash: 'sha256:abc123',
+    };
+
+    expect(input.receiptHash).toBe('sha256:abc123');
+  });
+
+  it('should accept optional fields', () => {
+    const input: ReceiptIssuedInput = {
+      receiptHash: 'sha256:abc123',
+      policyHash: 'sha256:policy',
+      issuer: 'https://api.example.com',
+      kid: '2025-01-01',
+      http: { method: 'POST', path: '/api/resource' },
+      durationMs: 42,
+    };
+
+    expect(input.policyHash).toBe('sha256:policy');
+    expect(input.issuer).toBe('https://api.example.com');
+    expect(input.kid).toBe('2025-01-01');
+    expect(input.http?.method).toBe('POST');
+    expect(input.durationMs).toBe(42);
+  });
+});
+
+describe('ReceiptVerifiedInput', () => {
+  it('should require receiptHash and valid', () => {
+    const input: ReceiptVerifiedInput = {
+      receiptHash: 'sha256:abc123',
+      valid: true,
+    };
+
+    expect(input.receiptHash).toBe('sha256:abc123');
+    expect(input.valid).toBe(true);
+  });
+
+  it('should accept reason code for failed verification', () => {
+    const input: ReceiptVerifiedInput = {
+      receiptHash: 'sha256:abc123',
+      valid: false,
+      reasonCode: 'SIGNATURE_INVALID',
+    };
+
+    expect(input.valid).toBe(false);
+    expect(input.reasonCode).toBe('SIGNATURE_INVALID');
+  });
+});
+
+describe('AccessDecisionInput', () => {
+  it('should require decision', () => {
+    const input: AccessDecisionInput = {
+      decision: 'allow',
+    };
+
+    expect(input.decision).toBe('allow');
+  });
+
+  it('should accept payment context', () => {
+    const input: AccessDecisionInput = {
+      decision: 'allow',
+      payment: {
+        rail: 'stripe',
+        amount: 9999,
+        currency: 'USD',
+      },
+    };
+
+    expect(input.payment?.rail).toBe('stripe');
+    expect(input.payment?.amount).toBe(9999);
+    expect(input.payment?.currency).toBe('USD');
+  });
+});
+
+describe('HttpContext', () => {
+  it('should accept method and path', () => {
+    const ctx: HttpContext = {
+      method: 'GET',
+      path: '/api/v1/resource',
+    };
+
+    expect(ctx.method).toBe('GET');
+    expect(ctx.path).toBe('/api/v1/resource');
+  });
+
+  it('should allow partial context', () => {
+    const methodOnly: HttpContext = { method: 'POST' };
+    const pathOnly: HttpContext = { path: '/health' };
+
+    expect(methodOnly.method).toBe('POST');
+    expect(pathOnly.path).toBe('/health');
+  });
+});
+
+describe('PaymentContext', () => {
+  it('should accept rail, amount, and currency', () => {
+    const ctx: PaymentContext = {
+      rail: 'x402',
+      amount: 1500,
+      currency: 'USD',
+    };
+
+    expect(ctx.rail).toBe('x402');
+    expect(ctx.amount).toBe(1500);
+    expect(ctx.currency).toBe('USD');
+  });
+});
+
+describe('TelemetryProvider', () => {
+  it('should define all required methods', () => {
+    const provider: TelemetryProvider = {
+      onReceiptIssued: () => {},
+      onReceiptVerified: () => {},
+      onAccessDecision: () => {},
+    };
+
+    expect(typeof provider.onReceiptIssued).toBe('function');
+    expect(typeof provider.onReceiptVerified).toBe('function');
+    expect(typeof provider.onAccessDecision).toBe('function');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"],
+  "references": [{ "path": "../kernel" }]
+}