observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/observability/trace-anomaly-detector.test.js

@@ -0,0 +1,224 @@
+/**
+ * Tests for the INV-2 runtime anomaly detection engine.
+ */
+import { describe, it } from 'vitest';
+import * as assert from 'node:assert';
+import { detectSpanAnomalies, buildAnomalySummary } from './trace-anomaly-detector.js';
+import { DEFAULT_DURATION_THRESHOLDS, DEFAULT_TOKEN_THRESHOLDS, } from './trace-anomaly-schemas.js';
+const BASE_TRACE_ID = 'a'.repeat(32);
+const BASE_SPAN_ID = 'b'.repeat(16);
+function makeSpan(overrides = {}) {
+    return {
+        traceId: BASE_TRACE_ID,
+        spanId: BASE_SPAN_ID,
+        name: 'hook:post-tool',
+        startTimeUnixNano: 1_700_000_000_000_000_000,
+        durationMs: 1,
+        ...overrides,
+    };
+}
+function uniqueIds(index) {
+    return {
+        traceId: String(index).padStart(32, '0'),
+        spanId: String(index).padStart(16, '0'),
+    };
+}
+describe('detectSpanAnomalies', () => {
+    it('returns no signals for a clean hook span', () => {
+        const result = detectSpanAnomalies([makeSpan()]);
+        assert.strictEqual(result.length, 1);
+        assert.strictEqual(result[0].overallSeverity, 'none');
+        assert.strictEqual(result[0].signals.length, 0);
+        assert.strictEqual(result[0].excluded, false);
+    });
+    describe('duration signal', () => {
+        it('fires warn when durationMs exceeds hook warn threshold', () => {
+            const span = makeSpan({ durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs + 1 });
+            const [anomaly] = detectSpanAnomalies([span]);
+            const durSignal = anomaly.signals.find(s => s.signal === 'duration');
+            assert.ok(durSignal, 'duration signal should fire');
+            assert.strictEqual(durSignal.severity, 'warn');
+        });
+        it('fires critical when durationMs exceeds hook critical threshold', () => {
+            const span = makeSpan({ durationMs: DEFAULT_DURATION_THRESHOLDS.hook.criticalMs + 1 });
+            const [anomaly] = detectSpanAnomalies([span]);
+            const durSignal = anomaly.signals.find(s => s.signal === 'duration');
+            assert.ok(durSignal, 'duration signal should fire');
+            assert.strictEqual(durSignal.severity, 'critical');
+            assert.strictEqual(anomaly.overallSeverity, 'critical');
+        });
+        it('does not fire when durationMs is below warn threshold', () => {
+            const span = makeSpan({ durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs - 1 });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'duration'));
+        });
+        it('uses endTimeUnixNano fallback when durationMs is absent', () => {
+            const startNs = 1_700_000_000_000_000_000;
+            const durationNs = (DEFAULT_DURATION_THRESHOLDS.hook.criticalMs + 10) * 1_000_000;
+            const span = makeSpan({
+                durationMs: undefined,
+                startTimeUnixNano: startNs,
+                endTimeUnixNano: startNs + durationNs,
+            });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(anomaly.signals.some(s => s.signal === 'duration' && s.severity === 'critical'));
+        });
+        it('uses agent thresholds for agent category spans', () => {
+            const span = makeSpan({
+                name: 'agent:run',
+                // 200ms would be critical for hook, but only warn for agent (threshold is 5000ms)
+                durationMs: DEFAULT_DURATION_THRESHOLDS.hook.criticalMs + 1,
+            });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.strictEqual(anomaly.category, 'agent');
+            assert.ok(!anomaly.signals.some(s => s.signal === 'duration'), 'no duration signal expected for agent at 200ms');
+        });
+    });
+    describe('error_status signal', () => {
+        it('fires error when status code is ERROR (2)', () => {
+            const span = makeSpan({ status: { code: 2, message: 'something failed' } });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(anomaly.signals.some(s => s.signal === 'error_status' && s.severity === 'error'));
+        });
+        it('does not fire for non-error status codes', () => {
+            const span = makeSpan({ status: { code: 0 } });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'error_status'));
+        });
+        it('excludes hook:tsc-check from error_status signal', () => {
+            const span = makeSpan({ name: 'hook:tsc-check', status: { code: 2 } });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.strictEqual(anomaly.excluded, true);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'error_status'), 'tsc-check should be excluded');
+        });
+    });
+    describe('token signals', () => {
+        it('fires input_tokens warn at warn threshold', () => {
+            const attrs = { 'gen_ai.usage.input_tokens': DEFAULT_TOKEN_THRESHOLDS.inputWarnTokens };
+            const span = makeSpan({ attributes: attrs });
+            const [anomaly] = detectSpanAnomalies([span]);
+            const sig = anomaly.signals.find(s => s.signal === 'input_tokens');
+            assert.ok(sig);
+            assert.strictEqual(sig.severity, 'warn');
+        });
+        it('fires input_tokens critical at critical threshold', () => {
+            const attrs = { 'gen_ai.usage.input_tokens': DEFAULT_TOKEN_THRESHOLDS.inputCriticalTokens };
+            const span = makeSpan({ attributes: attrs });
+            const [anomaly] = detectSpanAnomalies([span]);
+            const sig = anomaly.signals.find(s => s.signal === 'input_tokens');
+            assert.ok(sig);
+            assert.strictEqual(sig.severity, 'critical');
+        });
+        it('fires output_tokens warn at warn threshold', () => {
+            const attrs = { 'gen_ai.usage.output_tokens': DEFAULT_TOKEN_THRESHOLDS.outputWarnTokens };
+            const span = makeSpan({ attributes: attrs });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(anomaly.signals.some(s => s.signal === 'output_tokens' && s.severity === 'warn'));
+        });
+        it('does not fire when token attributes are absent', () => {
+            const [anomaly] = detectSpanAnomalies([makeSpan()]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'input_tokens' || s.signal === 'output_tokens'));
+        });
+        it('accepts string-typed token values', () => {
+            const attrs = { 'gen_ai.usage.input_tokens': String(DEFAULT_TOKEN_THRESHOLDS.inputCriticalTokens) };
+            const span = makeSpan({ attributes: attrs });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(anomaly.signals.some(s => s.signal === 'input_tokens' && s.severity === 'critical'));
+        });
+    });
+    describe('unknown_span_name signal', () => {
+        it('fires for span names not matching any known prefix', () => {
+            const span = makeSpan({ name: 'mystery:operation' });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(anomaly.signals.some(s => s.signal === 'unknown_span_name'));
+            assert.strictEqual(anomaly.category, 'unknown');
+        });
+        it('does not fire for known hook prefix', () => {
+            const span = makeSpan({ name: 'hook:session-start' });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'unknown_span_name'));
+        });
+        it('does not fire for known mcp prefix', () => {
+            const span = makeSpan({ name: 'mcp:call' });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'unknown_span_name'));
+        });
+    });
+    describe('span_count signal', () => {
+        it('fires when multiple spans share the same traceId', () => {
+            const traceId = 'c'.repeat(32);
+            const spans = [
+                makeSpan({ traceId, spanId: '1'.padStart(16, '0') }),
+                makeSpan({ traceId, spanId: '2'.padStart(16, '0') }),
+            ];
+            const results = detectSpanAnomalies(spans);
+            assert.ok(results.every(a => a.signals.some(s => s.signal === 'span_count')));
+        });
+        it('does not fire for single-span traces', () => {
+            const [anomaly] = detectSpanAnomalies([makeSpan()]);
+            assert.ok(!anomaly.signals.some(s => s.signal === 'span_count'));
+        });
+        it('does not fire when spans have different traceIds', () => {
+            const spans = [
+                makeSpan({ ...uniqueIds(1) }),
+                makeSpan({ ...uniqueIds(2) }),
+            ];
+            const results = detectSpanAnomalies(spans);
+            assert.ok(results.every(a => !a.signals.some(s => s.signal === 'span_count')));
+        });
+    });
+    describe('overall severity', () => {
+        it('reports the highest severity across multiple signals', () => {
+            const span = makeSpan({
+                durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs + 1,
+                status: { code: 2 },
+            });
+            const [anomaly] = detectSpanAnomalies([span]);
+            assert.strictEqual(anomaly.overallSeverity, 'error');
+        });
+        it('orders signals by severity descending', () => {
+            const span = makeSpan({
+                durationMs: DEFAULT_DURATION_THRESHOLDS.hook.criticalMs + 1,
+                attributes: { 'gen_ai.usage.input_tokens': DEFAULT_TOKEN_THRESHOLDS.inputWarnTokens },
+            });
+            const [anomaly] = detectSpanAnomalies([span]);
+            const severities = anomaly.signals.map(s => s.severity);
+            // critical should come before warn
+            const firstCriticalIdx = severities.indexOf('critical');
+            const firstWarnIdx = severities.indexOf('warn');
+            assert.ok(firstCriticalIdx < firstWarnIdx || firstWarnIdx === -1);
+        });
+    });
+});
+describe('buildAnomalySummary', () => {
+    it('counts total, anomalous, excluded, and severity breakdowns', () => {
+        const spans = [
+            makeSpan({ ...uniqueIds(1), durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs + 1 }),
+            makeSpan({ ...uniqueIds(2), durationMs: 1 }), // clean
+            makeSpan({ ...uniqueIds(3), name: 'hook:tsc-check', status: { code: 2 } }), // excluded
+        ];
+        const anomalies = detectSpanAnomalies(spans);
+        const summary = buildAnomalySummary(anomalies, 'session-xyz');
+        assert.strictEqual(summary.totalSpans, 3);
+        assert.strictEqual(summary.anomalousSpans, 1);
+        assert.strictEqual(summary.excludedSpans, 1);
+        assert.strictEqual(summary.warnCount, 1);
+        assert.strictEqual(summary.errorCount, 0);
+        assert.strictEqual(summary.criticalCount, 0);
+        assert.strictEqual(summary.sessionId, 'session-xyz');
+        assert.ok(summary.analyzedAt);
+    });
+    it('populates signalCounts per fired signal type', () => {
+        const spans = [
+            makeSpan({ ...uniqueIds(1), durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs + 1 }),
+            makeSpan({ ...uniqueIds(2), durationMs: DEFAULT_DURATION_THRESHOLDS.hook.warnMs + 1 }),
+        ];
+        const summary = buildAnomalySummary(detectSpanAnomalies(spans));
+        assert.strictEqual(summary.signalCounts['duration'], 2);
+    });
+    it('omits sessionId when not provided', () => {
+        const summary = buildAnomalySummary(detectSpanAnomalies([makeSpan()]));
+        assert.ok(!('sessionId' in summary));
+    });
+});
+//# sourceMappingURL=trace-anomaly-detector.test.js.map

package/dist/lib/observability/trace-anomaly-detector.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-detector.test.js","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-detector.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/observability/trace-anomaly-schemas.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Zod schemas for per-span anomaly detection (INV-2).
+ *
+ * ## Data-grounded design (2026-04-06)
+ *
+ * Analysis of 23,448 spans across 3 real sessions revealed:
+ * - All traces are single-span (each hook invocation = 1 span, no parent-child)
+ * - 21 distinct span names; hook:builtin-pre/post-tool is 77% of volume
+ * - Median duration: 1.44ms; p95: 4.78ms; warn at >50ms, critical at >200ms
+ * - Token data is sparse (~2% coverage): input p95=17K, output p95=28K
+ * - 5.6% error rate from hook:tsc-check only ("require is not defined" — known false positive)
+ *
+ * ## OTel spec grounding
+ *
+ * No OTel semconv defines span count, nesting, or complexity limits.
+ * Anomaly signals are anchored to:
+ * - gen_ai.usage.input_tokens / gen_ai.usage.output_tokens (Development stability)
+ * - span.status.code (UNSET=0, OK=1, ERROR=2)
+ * - Duration derived from startTime/endTime HrTime tuples
+ *
+ * ## Recommendation for OTEL2 implementation
+ *
+ * - Use per-span-name thresholds (21 known names; table-driven)
+ * - Primary signals: duration, error_status, input_tokens, output_tokens
+ * - Nesting depth: NOT applicable (data always single-span)
+ * - Span count per trace: flag if >2 (instrumentation loop indicator)
+ * - Unknown span names: flag as anomaly (instrumentation drift indicator)
+ * - Exclude hook:tsc-check from error_status signal (permanent false positive)
+ */
+import { z } from 'zod';
+/**
+ * Span category derived from span name prefix.
+ * Used to select the correct duration threshold table.
+ */
+export declare const spanCategorySchema: z.ZodEnum<{
+    unknown: "unknown";
+    tool: "tool";
+    agent: "agent";
+    hook: "hook";
+    mcp: "mcp";
+}>;
+export type SpanCategory = z.infer<typeof spanCategorySchema>;
+/** Four-level severity mirroring OpenTelemetry log severity groupings. */
+export declare const anomalySeveritySchema: z.ZodEnum<{
+    warn: "warn";
+    error: "error";
+    critical: "critical";
+    none: "none";
+}>;
+export type AnomalySeverity = z.infer<typeof anomalySeveritySchema>;
+/**
+ * Signal types detectable without cross-span correlation.
+ * All signals are derivable from a single ExportedSpan object.
+ */
+export declare const anomalySignalSchema: z.ZodEnum<{
+    input_tokens: "input_tokens";
+    output_tokens: "output_tokens";
+    duration: "duration";
+    error_status: "error_status";
+    unknown_span_name: "unknown_span_name";
+    span_count: "span_count";
+}>;
+export type AnomalySignal = z.infer<typeof anomalySignalSchema>;
+/** Duration thresholds per span category (milliseconds). */
+export declare const durationThresholdsSchema: z.ZodObject<{
+    warnMs: z.ZodNumber;
+    criticalMs: z.ZodNumber;
+}, z.core.$strip>;
+export type DurationThresholds = z.infer<typeof durationThresholdsSchema>;
+/** Token anomaly thresholds (token counts). */
+export declare const tokenAnomalyThresholdsSchema: z.ZodObject<{
+    inputWarnTokens: z.ZodNumber;
+    inputCriticalTokens: z.ZodNumber;
+    outputWarnTokens: z.ZodNumber;
+    outputCriticalTokens: z.ZodNumber;
+}, z.core.$strip>;
+export type TokenAnomalyThresholds = z.infer<typeof tokenAnomalyThresholdsSchema>;
+/** A single fired anomaly signal with observed vs threshold values. */
+export declare const signalAnomalySchema: z.ZodObject<{
+    signal: z.ZodEnum<{
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        duration: "duration";
+        error_status: "error_status";
+        unknown_span_name: "unknown_span_name";
+        span_count: "span_count";
+    }>;
+    severity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        critical: "critical";
+        none: "none";
+    }>;
+    observed: z.ZodOptional<z.ZodNumber>;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SignalAnomaly = z.infer<typeof signalAnomalySchema>;
+/** Per-span anomaly assessment. One record per analyzed span. */
+export declare const spanAnomalySchema: z.ZodObject<{
+    spanId: z.ZodString;
+    traceId: z.ZodString;
+    spanName: z.ZodString;
+    category: z.ZodEnum<{
+        unknown: "unknown";
+        tool: "tool";
+        agent: "agent";
+        hook: "hook";
+        mcp: "mcp";
+    }>;
+    overallSeverity: z.ZodEnum<{
+        warn: "warn";
+        error: "error";
+        critical: "critical";
+        none: "none";
+    }>;
+    signals: z.ZodArray<z.ZodObject<{
+        signal: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            output_tokens: "output_tokens";
+            duration: "duration";
+            error_status: "error_status";
+            unknown_span_name: "unknown_span_name";
+            span_count: "span_count";
+        }>;
+        severity: z.ZodEnum<{
+            warn: "warn";
+            error: "error";
+            critical: "critical";
+            none: "none";
+        }>;
+        observed: z.ZodOptional<z.ZodNumber>;
+        threshold: z.ZodOptional<z.ZodNumber>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    excluded: z.ZodBoolean;
+}, z.core.$strip>;
+export type SpanAnomaly = z.infer<typeof spanAnomalySchema>;
+/** Aggregated anomaly counts for a session or time window. */
+export declare const anomalySummarySchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    analyzedAt: z.ZodISODateTime;
+    totalSpans: z.ZodNumber;
+    anomalousSpans: z.ZodNumber;
+    excludedSpans: z.ZodNumber;
+    criticalCount: z.ZodNumber;
+    errorCount: z.ZodNumber;
+    warnCount: z.ZodNumber;
+    signalCounts: z.ZodRecord<z.ZodEnum<{
+        input_tokens: "input_tokens";
+        output_tokens: "output_tokens";
+        duration: "duration";
+        error_status: "error_status";
+        unknown_span_name: "unknown_span_name";
+        span_count: "span_count";
+    }>, z.ZodNumber>;
+}, z.core.$strip>;
+export type AnomalySummary = z.infer<typeof anomalySummarySchema>;
+/**
+ * Span name prefixes that identify each category.
+ * First matching prefix wins; falls back to 'unknown'.
+ */
+export declare const SPAN_CATEGORY_PREFIXES: Record<SpanCategory, readonly string[]>;
+/**
+ * Duration thresholds per category.
+ *
+ * Hook baseline: median 1.44ms, p95 4.78ms.
+ * Warn = 10× p95 baseline; critical = 40× p95 baseline.
+ * Agent/tool/mcp are intentionally lenient (long-running operations expected).
+ */
+export declare const DEFAULT_DURATION_THRESHOLDS: Record<SpanCategory, DurationThresholds>;
+/**
+ * Token anomaly thresholds.
+ * Derived from 2026-04-06 session data (sparse coverage, ~2% of spans).
+ */
+export declare const DEFAULT_TOKEN_THRESHOLDS: TokenAnomalyThresholds;
+/**
+ * Span names excluded from error_status anomaly signal.
+ *
+ * hook:tsc-check always fails with "require is not defined" in ESM context.
+ * This is a permanent instrumentation false positive, not a real error.
+ */
+export declare const ERROR_STATUS_EXCLUSIONS: Set<string>;
+/**
+ * Maximum expected spans per trace in current telemetry.
+ * Data shows all traces are single-span. Flag if exceeded.
+ */
+export declare const MAX_SPANS_PER_TRACE = 1;
+//# sourceMappingURL=trace-anomaly-schemas.d.ts.map

package/dist/lib/observability/trace-anomaly-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;EAAsD,CAAC;AACtF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB;;;;;EAAgD,CAAC;AACnF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,4DAA4D;AAC5D,eAAO,MAAM,wBAAwB;;;iBAKmC,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,+CAA+C;AAC/C,eAAO,MAAM,4BAA4B;;;;;iBASvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAMlF,uEAAuE;AACvE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAS9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iEAAiE;AACjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;iBAW/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAM1E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,YAAY,EAAE,kBAAkB,CAMhF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,sBAKtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,aAElC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC"}

package/dist/lib/observability/trace-anomaly-schemas.js

@@ -0,0 +1,167 @@
+/**
+ * Zod schemas for per-span anomaly detection (INV-2).
+ *
+ * ## Data-grounded design (2026-04-06)
+ *
+ * Analysis of 23,448 spans across 3 real sessions revealed:
+ * - All traces are single-span (each hook invocation = 1 span, no parent-child)
+ * - 21 distinct span names; hook:builtin-pre/post-tool is 77% of volume
+ * - Median duration: 1.44ms; p95: 4.78ms; warn at >50ms, critical at >200ms
+ * - Token data is sparse (~2% coverage): input p95=17K, output p95=28K
+ * - 5.6% error rate from hook:tsc-check only ("require is not defined" — known false positive)
+ *
+ * ## OTel spec grounding
+ *
+ * No OTel semconv defines span count, nesting, or complexity limits.
+ * Anomaly signals are anchored to:
+ * - gen_ai.usage.input_tokens / gen_ai.usage.output_tokens (Development stability)
+ * - span.status.code (UNSET=0, OK=1, ERROR=2)
+ * - Duration derived from startTime/endTime HrTime tuples
+ *
+ * ## Recommendation for OTEL2 implementation
+ *
+ * - Use per-span-name thresholds (21 known names; table-driven)
+ * - Primary signals: duration, error_status, input_tokens, output_tokens
+ * - Nesting depth: NOT applicable (data always single-span)
+ * - Span count per trace: flag if >2 (instrumentation loop indicator)
+ * - Unknown span names: flag as anomaly (instrumentation drift indicator)
+ * - Exclude hook:tsc-check from error_status signal (permanent false positive)
+ */
+import { z } from 'zod';
+import { SessionIdSchema, SpanIdSchema, TraceIdSchema } from '../core/shared-schemas.js';
+// ============================================================================
+// Enums
+// ============================================================================
+/**
+ * Span category derived from span name prefix.
+ * Used to select the correct duration threshold table.
+ */
+export const spanCategorySchema = z.enum(['hook', 'agent', 'tool', 'mcp', 'unknown']);
+/** Four-level severity mirroring OpenTelemetry log severity groupings. */
+export const anomalySeveritySchema = z.enum(['none', 'warn', 'error', 'critical']);
+/**
+ * Signal types detectable without cross-span correlation.
+ * All signals are derivable from a single ExportedSpan object.
+ */
+export const anomalySignalSchema = z.enum([
+    'duration', // span took longer than per-category threshold
+    'error_status', // span.status.code === 2 (ERROR)
+    'input_tokens', // gen_ai.usage.input_tokens exceeded threshold
+    'output_tokens', // gen_ai.usage.output_tokens exceeded threshold
+    'unknown_span_name', // name not in known-names set (instrumentation drift)
+    'span_count', // >1 span per trace (instrumentation loop)
+]);
+// ============================================================================
+// Threshold schemas (configuration layer)
+// ============================================================================
+/** Duration thresholds per span category (milliseconds). */
+export const durationThresholdsSchema = z.object({
+    /** Warn if duration exceeds this. Data-derived: hook p95 ≈ 5ms → warn at 10× (50ms). */
+    warnMs: z.number().nonnegative(),
+    /** Critical if duration exceeds this. */
+    criticalMs: z.number().nonnegative(),
+}).refine(t => t.criticalMs > t.warnMs, 'criticalMs must exceed warnMs');
+/** Token anomaly thresholds (token counts). */
+export const tokenAnomalyThresholdsSchema = z.object({
+    /** Warn on input_tokens ≥ this. Data-derived: p95 = 17K. */
+    inputWarnTokens: z.number().nonnegative(),
+    /** Critical on input_tokens ≥ this. Data-derived: p99 ≈ 25K. */
+    inputCriticalTokens: z.number().nonnegative(),
+    /** Warn on output_tokens ≥ this. Data-derived: p95 = 28K. */
+    outputWarnTokens: z.number().nonnegative(),
+    /** Critical on output_tokens ≥ this. Data-derived: p99 ≈ 55K. */
+    outputCriticalTokens: z.number().nonnegative(),
+});
+// ============================================================================
+// Detection result schemas
+// ============================================================================
+/** A single fired anomaly signal with observed vs threshold values. */
+export const signalAnomalySchema = z.object({
+    signal: anomalySignalSchema,
+    severity: anomalySeveritySchema,
+    /** Numeric observed value (ms for duration, token count for tokens). */
+    observed: z.number().optional(),
+    /** Threshold that was exceeded. */
+    threshold: z.number().optional(),
+    /** Human-readable detail for console output. */
+    detail: z.string().optional(),
+});
+/** Per-span anomaly assessment. One record per analyzed span. */
+export const spanAnomalySchema = z.object({
+    spanId: SpanIdSchema,
+    traceId: TraceIdSchema,
+    spanName: z.string().min(1),
+    category: spanCategorySchema,
+    /** Highest severity across all fired signals. */
+    overallSeverity: anomalySeveritySchema,
+    /** All fired signals, ordered by severity descending. */
+    signals: z.array(signalAnomalySchema),
+    /** True if this span matched the known false-positive exclude list. */
+    excluded: z.boolean(),
+});
+/** Aggregated anomaly counts for a session or time window. */
+export const anomalySummarySchema = z.object({
+    sessionId: SessionIdSchema.optional(),
+    analyzedAt: z.iso.datetime(),
+    totalSpans: z.number().nonnegative(),
+    anomalousSpans: z.number().nonnegative(),
+    excludedSpans: z.number().nonnegative(),
+    criticalCount: z.number().nonnegative(),
+    errorCount: z.number().nonnegative(),
+    warnCount: z.number().nonnegative(),
+    /** Per-signal fire counts (for surfacing top anomaly types). */
+    signalCounts: z.record(anomalySignalSchema, z.number().nonnegative()),
+});
+// ============================================================================
+// Data-grounded defaults (derived from 2026-04-06 analysis)
+// ============================================================================
+/**
+ * Span name prefixes that identify each category.
+ * First matching prefix wins; falls back to 'unknown'.
+ */
+export const SPAN_CATEGORY_PREFIXES = {
+    hook: ['hook:'],
+    agent: ['agent:', 'gen_ai.agent', 'invoke_agent'],
+    tool: ['tool:', 'execute_tool'],
+    mcp: ['mcp:'],
+    unknown: [],
+};
+/**
+ * Duration thresholds per category.
+ *
+ * Hook baseline: median 1.44ms, p95 4.78ms.
+ * Warn = 10× p95 baseline; critical = 40× p95 baseline.
+ * Agent/tool/mcp are intentionally lenient (long-running operations expected).
+ */
+export const DEFAULT_DURATION_THRESHOLDS = {
+    hook: { warnMs: 50, criticalMs: 200 },
+    agent: { warnMs: 5_000, criticalMs: 30_000 },
+    tool: { warnMs: 500, criticalMs: 5_000 },
+    mcp: { warnMs: 1_000, criticalMs: 10_000 },
+    unknown: { warnMs: 50, criticalMs: 200 },
+};
+/**
+ * Token anomaly thresholds.
+ * Derived from 2026-04-06 session data (sparse coverage, ~2% of spans).
+ */
+export const DEFAULT_TOKEN_THRESHOLDS = {
+    inputWarnTokens: 17_000,
+    inputCriticalTokens: 25_000,
+    outputWarnTokens: 28_000,
+    outputCriticalTokens: 55_000,
+};
+/**
+ * Span names excluded from error_status anomaly signal.
+ *
+ * hook:tsc-check always fails with "require is not defined" in ESM context.
+ * This is a permanent instrumentation false positive, not a real error.
+ */
+export const ERROR_STATUS_EXCLUSIONS = new Set([
+    'hook:tsc-check',
+]);
+/**
+ * Maximum expected spans per trace in current telemetry.
+ * Data shows all traces are single-span. Flag if exceeded.
+ */
+export const MAX_SPANS_PER_TRACE = 1;
+//# sourceMappingURL=trace-anomaly-schemas.js.map

package/dist/lib/observability/trace-anomaly-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-schemas.js","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-schemas.ts"],"names":[],"mappings":"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"}