observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/observability/render-trace-tree.js

@@ -0,0 +1,95 @@
+/**
+ * ASCII trace tree rendering using archy.
+ * Groups spans by session.id attribute, sorts by startTime, renders each session as a tree.
+ *
+ * OTEL3 — ref: docs/BACKLOG.md
+ */
+import archy from 'archy';
+const STATUS_CODE_ERROR = 2;
+const DURATION_WARN_MS = 1000;
+const NANOS_PER_MS = 1_000_000;
+const NANOS_PER_SECOND = 1_000_000_000;
+const SESSION_ID_ATTR = 'session.id';
+const UNKNOWN_SESSION = '(unknown-session)';
+/** ANSI escape codes */
+const ANSI_RED = '\x1b[31m';
+const ANSI_YELLOW = '\x1b[33m';
+const ANSI_RESET = '\x1b[0m';
+function durationMs(span) {
+    if (span.duration) {
+        const [secs, nanos] = span.duration;
+        return secs * 1000 + nanos / NANOS_PER_MS;
+    }
+    if (span.startTime && span.endTime) {
+        const startNs = span.startTime[0] * NANOS_PER_SECOND + span.startTime[1];
+        const endNs = span.endTime[0] * NANOS_PER_SECOND + span.endTime[1];
+        return (endNs - startNs) / NANOS_PER_MS;
+    }
+    return null;
+}
+function spanLabel(span, color) {
+    const ms = durationMs(span);
+    const durationStr = ms !== null ? `${ms.toFixed(1)}ms` : '?ms';
+    const statusCode = span.status?.code ?? 0;
+    const statusStr = statusCode === STATUS_CODE_ERROR ? 'ERROR' : 'OK';
+    let label = `${span.name} (${durationStr}) [${statusStr}]`;
+    if (color) {
+        if (statusCode === STATUS_CODE_ERROR) {
+            label = `${ANSI_RED}${label}${ANSI_RESET}`;
+        }
+        else if (ms !== null && ms > DURATION_WARN_MS) {
+            label = `${ANSI_YELLOW}${label}${ANSI_RESET}`;
+        }
+    }
+    return label;
+}
+function startTimeNs(span) {
+    if (!span.startTime)
+        return 0;
+    return span.startTime[0] * NANOS_PER_SECOND + span.startTime[1];
+}
+function sessionKey(span) {
+    const sessionId = span.attributes?.[SESSION_ID_ATTR];
+    return typeof sessionId === 'string' && sessionId ? sessionId : UNKNOWN_SESSION;
+}
+/**
+ * Render a flat array of spans as ASCII trees, grouped by session.id.
+ *
+ * @param spans - Array of spans from JSONL telemetry (ExportedSpan-compatible)
+ * @param options - Rendering options
+ * @returns ASCII tree string (archy output); caller decides whether to print or pipe
+ */
+export function renderTraceTree(spans, options = {}) {
+    const color = options.color ?? true;
+    // Group spans by session
+    const sessionMap = new Map();
+    for (const span of spans) {
+        const key = sessionKey(span);
+        const group = sessionMap.get(key);
+        if (group) {
+            group.push(span);
+        }
+        else {
+            sessionMap.set(key, [span]);
+        }
+    }
+    const parts = [];
+    for (const [sessionId, sessionSpans] of sessionMap) {
+        // Sort spans by startTime within each session
+        const sorted = [...sessionSpans].sort((a, b) => startTimeNs(a) - startTimeNs(b));
+        // Determine session date from first span startTime
+        const firstSpan = sorted[0];
+        let dateStr = '';
+        if (firstSpan?.startTime) {
+            const date = new Date(firstSpan.startTime[0] * 1000);
+            dateStr = ` ${date.toISOString().slice(0, 10)}`;
+        }
+        const tree = {
+            label: `session:${sessionId}${dateStr} (${sorted.length} spans)`,
+            nodes: sorted.map(span => spanLabel(span, color)),
+        };
+        parts.push(archy(tree));
+    }
+    return parts.join('\n');
+}
+//# sourceMappingURL=render-trace-tree.js.map

package/dist/lib/observability/render-trace-tree.js.map

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

package/dist/lib/observability/render-trace-tree.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for ASCII trace tree rendering (OTEL3)
+ */
+export {};
+//# sourceMappingURL=render-trace-tree.test.d.ts.map

package/dist/lib/observability/render-trace-tree.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-trace-tree.test.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/render-trace-tree.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/lib/observability/render-trace-tree.test.js

@@ -0,0 +1,97 @@
+/**
+ * Tests for ASCII trace tree rendering (OTEL3)
+ */
+import { describe, it } from 'vitest';
+import * as assert from 'node:assert';
+import { renderTraceTree } from './render-trace-tree.js';
+const STATUS_OK = 0;
+const STATUS_ERROR = 2;
+const SESSION_ID_ATTR = 'session.id';
+function makeSpan(overrides = {}) {
+    const { sessionId, ...rest } = overrides;
+    return {
+        name: 'test-span',
+        startTime: [1_700_000_000, 0],
+        endTime: [1_700_000_000, 100_000_000],
+        duration: [0, 100_000_000],
+        status: { code: STATUS_OK },
+        attributes: sessionId ? { [SESSION_ID_ATTR]: sessionId } : {},
+        ...rest,
+    };
+}
+describe('renderTraceTree', () => {
+    it('returns empty string for empty input', () => {
+        assert.strictEqual(renderTraceTree([]), '');
+    });
+    it('renders a span with name and duration', () => {
+        const span = makeSpan({ name: 'my-span', duration: [0, 50_000_000] });
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('my-span'), 'should include span name');
+        assert.ok(output.includes('50.0ms'), 'should include duration');
+    });
+    it('groups spans by session.id', () => {
+        const spans = [
+            makeSpan({ name: 'span-a', sessionId: 'session-1' }),
+            makeSpan({ name: 'span-b', sessionId: 'session-2' }),
+            makeSpan({ name: 'span-c', sessionId: 'session-1' }),
+        ];
+        const output = renderTraceTree(spans, { color: false });
+        assert.ok(output.includes('session-1'), 'should include session-1 header');
+        assert.ok(output.includes('session-2'), 'should include session-2 header');
+        assert.ok(output.includes('span-a'), 'should include span-a');
+        assert.ok(output.includes('span-b'), 'should include span-b');
+        assert.ok(output.includes('span-c'), 'should include span-c');
+    });
+    it('uses (unknown-session) when session.id attribute is absent', () => {
+        const span = makeSpan({ name: 'no-session-span' });
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('unknown-session'), 'should include unknown-session label');
+        assert.ok(output.includes('no-session-span'), 'should include span name');
+    });
+    it('includes [ERROR] label for error spans', () => {
+        const span = makeSpan({ name: 'err-span', status: { code: STATUS_ERROR }, sessionId: 's1' });
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('[ERROR]'), 'should include [ERROR] status');
+    });
+    it('includes [OK] label for ok spans', () => {
+        const span = makeSpan({ name: 'ok-span', status: { code: STATUS_OK }, sessionId: 's1' });
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('[OK]'), 'should include [OK] status');
+    });
+    it('includes span count in session header', () => {
+        const spans = [
+            makeSpan({ sessionId: 'sess' }),
+            makeSpan({ sessionId: 'sess' }),
+            makeSpan({ sessionId: 'sess' }),
+        ];
+        const output = renderTraceTree(spans, { color: false });
+        assert.ok(output.includes('3 spans'), 'should show span count');
+    });
+    it('sorts spans by startTime within session', () => {
+        const spans = [
+            makeSpan({ name: 'second', startTime: [1_700_000_001, 0], sessionId: 'sess' }),
+            makeSpan({ name: 'first', startTime: [1_700_000_000, 0], sessionId: 'sess' }),
+        ];
+        const output = renderTraceTree(spans, { color: false });
+        const firstIdx = output.indexOf('first');
+        const secondIdx = output.indexOf('second');
+        assert.ok(firstIdx < secondIdx, 'first span should appear before second span');
+    });
+    it('handles spans with no startTime or duration', () => {
+        const span = { name: 'bare-span' };
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('bare-span'), 'should include span name');
+        assert.ok(output.includes('?ms'), 'should show ?ms for unknown duration');
+    });
+    it('computes duration from startTime/endTime when duration field is absent', () => {
+        const span = makeSpan({
+            name: 'computed',
+            startTime: [1_700_000_000, 0],
+            endTime: [1_700_000_000, 200_000_000],
+            duration: undefined,
+        });
+        const output = renderTraceTree([span], { color: false });
+        assert.ok(output.includes('200.0ms'), 'should compute 200ms from start/end');
+    });
+});
+//# sourceMappingURL=render-trace-tree.test.js.map

package/dist/lib/observability/render-trace-tree.test.js.map

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

package/dist/lib/observability/span-attributes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OTel attribute sanitization utilities.
+ *
+ * Provides key/value truncation per OTel spec limits and span kind mapping.
+ * Extracted from instrumentation.ts to allow independent testing and reuse.
+ */
+import type { SpanKind as OtelSpanKind } from '@opentelemetry/api';
+import type { SpanKind } from './instrumentation.js';
+/** Max attribute key length per OTel spec */
+export declare const OTEL_MAX_ATTR_KEY_LENGTH = 128;
+/** Max attribute value length per OTel spec */
+export declare const OTEL_MAX_ATTR_VALUE_LENGTH: number;
+/**
+ * Reset truncation log sampling counter.
+ * @internal For testing only — do not call in production code.
+ */
+export declare function resetTruncationLogStateForTesting(): void;
+/**
+ * Get OTel SpanKind value from loaded API.
+ */
+export declare function getOtelSpanKind(api: typeof import('@opentelemetry/api'), kind: SpanKind): OtelSpanKind;
+/**
+ * Filter out undefined values and sanitize attributes per OTel spec.
+ * H4: Truncates keys and string values to prevent exporter issues.
+ */
+export declare function filterUndefinedAttributes(attrs: Record<string, string | number | boolean | undefined>): Record<string, string | number | boolean>;
+//# sourceMappingURL=span-attributes.d.ts.map

package/dist/lib/observability/span-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-attributes.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/span-attributes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AASrD,6CAA6C;AAC7C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,+CAA+C;AAC/C,eAAO,MAAM,0BAA0B,QAAW,CAAC;AAKnD;;;GAGG;AACH,wBAAgB,iCAAiC,IAAI,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,oBAAoB,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,YAAY,CAetG;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC3D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAqC3C"}

package/dist/lib/observability/span-attributes.js

@@ -0,0 +1,85 @@
+/**
+ * OTel attribute sanitization utilities.
+ *
+ * Provides key/value truncation per OTel spec limits and span kind mapping.
+ * Extracted from instrumentation.ts to allow independent testing and reuse.
+ */
+import { BYTES, PERCENT_MULTIPLIER } from '../core/units.js';
+import { createLogger } from '../core/logger.js';
+// Intentionally uses 'instrumentation' component to keep attribute truncation logs
+// co-located with other instrumentation diagnostics in log dashboards.
+const logger = createLogger('instrumentation');
+// OTel spec attribute truncation limits (used for internal telemetry spans only).
+// Distinct from shared-schemas.ts MAX_ATTR_{KEY,VALUE}_LENGTH which are MCP tool
+// input validation bounds (100/500) — intentionally more conservative.
+/** Max attribute key length per OTel spec */
+export const OTEL_MAX_ATTR_KEY_LENGTH = 128;
+/** Max attribute value length per OTel spec */
+export const OTEL_MAX_ATTR_VALUE_LENGTH = BYTES.KB;
+// H4: Sampling state for truncation logging to prevent log spam (module-private)
+const truncationLogState = { count: 0 };
+/**
+ * Reset truncation log sampling counter.
+ * @internal For testing only — do not call in production code.
+ */
+export function resetTruncationLogStateForTesting() {
+    truncationLogState.count = 0;
+}
+/**
+ * Get OTel SpanKind value from loaded API.
+ */
+export function getOtelSpanKind(api, kind) {
+    switch (kind) {
+        case 'INTERNAL':
+            return api.SpanKind.INTERNAL;
+        case 'SERVER':
+            return api.SpanKind.SERVER;
+        case 'CLIENT':
+            return api.SpanKind.CLIENT;
+        case 'PRODUCER':
+            return api.SpanKind.PRODUCER;
+        case 'CONSUMER':
+            return api.SpanKind.CONSUMER;
+        default:
+            return api.SpanKind.INTERNAL;
+    }
+}
+/**
+ * Filter out undefined values and sanitize attributes per OTel spec.
+ * H4: Truncates keys and string values to prevent exporter issues.
+ */
+export function filterUndefinedAttributes(attrs) {
+    const result = {};
+    for (let [key, value] of Object.entries(attrs)) {
+        if (value === undefined)
+            continue;
+        const originalKey = key;
+        const originalValue = value;
+        // Truncate key if too long
+        if (key.length > OTEL_MAX_ATTR_KEY_LENGTH) {
+            key = key.substring(0, OTEL_MAX_ATTR_KEY_LENGTH);
+        }
+        // Truncate string values if too long
+        if (typeof value === 'string' && value.length > OTEL_MAX_ATTR_VALUE_LENGTH) {
+            value = value.substring(0, OTEL_MAX_ATTR_VALUE_LENGTH);
+        }
+        // H4 fix: Log truncation with sampling to prevent log spam
+        if (key !== originalKey || value !== originalValue) {
+            truncationLogState.count++;
+            // Log first occurrence, then sample every 100th
+            if (truncationLogState.count === 1 || truncationLogState.count % PERCENT_MULTIPLIER === 0) {
+                logger.debug('Attribute truncated', {
+                    originalKeyLength: originalKey.length,
+                    originalValueLength: typeof originalValue === 'string' ? originalValue.length : undefined,
+                    truncatedKey: key !== originalKey,
+                    truncatedValue: value !== originalValue,
+                    totalTruncations: truncationLogState.count,
+                    sampleRate: truncationLogState.count === 1 ? 'first' : '1/100',
+                });
+            }
+        }
+        result[key] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=span-attributes.js.map

package/dist/lib/observability/span-attributes.js.map

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

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

@@ -0,0 +1,23 @@
+/**
+ * Runtime anomaly detection engine for per-span telemetry (INV-2).
+ *
+ * Consumes TraceSpan records from the local backend and fires anomaly signals
+ * based on the data-grounded thresholds in trace-anomaly-schemas.ts.
+ *
+ * Design constraints (from 2026-04-06 data analysis):
+ * - All current traces are single-span — span_count signal flags instrumentation loops
+ * - hook:tsc-check permanently produces error_status (false positive) — excluded
+ * - Token attributes have ~2% coverage; absence is not anomalous
+ */
+import type { TraceSpan } from '../../backends/index.js';
+import { type SpanAnomaly, type AnomalySummary } from './trace-anomaly-schemas.js';
+/**
+ * Analyze an array of TraceSpan records and return per-span anomaly results.
+ * Spans with no signals fired will have overallSeverity === 'none'.
+ */
+export declare function detectSpanAnomalies(spans: TraceSpan[]): SpanAnomaly[];
+/**
+ * Aggregate per-span anomaly results into a summary.
+ */
+export declare function buildAnomalySummary(anomalies: SpanAnomaly[], sessionId?: string): AnomalySummary;
+//# sourceMappingURL=trace-anomaly-detector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-detector.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EASpB,MAAM,4BAA4B,CAAC;AAkKpC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,EAAE,CAUrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,WAAW,EAAE,EACxB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CA+BhB"}

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

@@ -0,0 +1,211 @@
+/**
+ * Runtime anomaly detection engine for per-span telemetry (INV-2).
+ *
+ * Consumes TraceSpan records from the local backend and fires anomaly signals
+ * based on the data-grounded thresholds in trace-anomaly-schemas.ts.
+ *
+ * Design constraints (from 2026-04-06 data analysis):
+ * - All current traces are single-span — span_count signal flags instrumentation loops
+ * - hook:tsc-check permanently produces error_status (false positive) — excluded
+ * - Token attributes have ~2% coverage; absence is not anomalous
+ */
+import { SPAN_CATEGORY_PREFIXES, DEFAULT_DURATION_THRESHOLDS, DEFAULT_TOKEN_THRESHOLDS, ERROR_STATUS_EXCLUSIONS, MAX_SPANS_PER_TRACE, } from './trace-anomaly-schemas.js';
+const STATUS_CODE_ERROR = 2;
+const ATTR_INPUT_TOKENS = 'gen_ai.usage.input_tokens';
+const ATTR_OUTPUT_TOKENS = 'gen_ai.usage.output_tokens';
+const SEVERITY_ORDER = ['none', 'warn', 'error', 'critical'];
+function maxSeverity(a, b) {
+    return SEVERITY_ORDER[Math.max(SEVERITY_ORDER.indexOf(a), SEVERITY_ORDER.indexOf(b))];
+}
+function classifyCategory(name) {
+    for (const [cat, prefixes] of Object.entries(SPAN_CATEGORY_PREFIXES)) {
+        if (cat === 'unknown')
+            continue;
+        if (prefixes.some(p => name.startsWith(p)))
+            return cat;
+    }
+    return 'unknown';
+}
+function numericAttr(attrs, key) {
+    const val = attrs?.[key];
+    if (typeof val === 'number')
+        return val;
+    if (typeof val === 'string') {
+        const n = Number(val);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+/** Compute durationMs from TraceSpan fields (durationMs preferred; falls back to nano diff). */
+function computeDurationMs(span) {
+    if (span.durationMs !== undefined)
+        return span.durationMs;
+    if (span.endTimeUnixNano !== undefined) {
+        return (span.endTimeUnixNano - span.startTimeUnixNano) / 1_000_000;
+    }
+    return undefined;
+}
+/** Fire anomaly signals for a single span, given trace-level span count. */
+function analyzeSpan(span, spansInTrace) {
+    const category = classifyCategory(span.name);
+    const excluded = ERROR_STATUS_EXCLUSIONS.has(span.name);
+    const signals = [];
+    // --- duration ---
+    const durationMs = computeDurationMs(span);
+    if (durationMs !== undefined) {
+        const thresholds = DEFAULT_DURATION_THRESHOLDS[category];
+        if (durationMs >= thresholds.criticalMs) {
+            signals.push({
+                signal: 'duration',
+                severity: 'critical',
+                observed: durationMs,
+                threshold: thresholds.criticalMs,
+                detail: `${durationMs.toFixed(1)}ms >= critical threshold ${thresholds.criticalMs}ms`,
+            });
+        }
+        else if (durationMs >= thresholds.warnMs) {
+            signals.push({
+                signal: 'duration',
+                severity: 'warn',
+                observed: durationMs,
+                threshold: thresholds.warnMs,
+                detail: `${durationMs.toFixed(1)}ms >= warn threshold ${thresholds.warnMs}ms`,
+            });
+        }
+    }
+    // --- error_status ---
+    if (!excluded && span.status?.code === STATUS_CODE_ERROR) {
+        signals.push({
+            signal: 'error_status',
+            severity: 'error',
+            detail: span.status.message
+                ? `ERROR: ${span.status.message}`
+                : 'span status code is ERROR (2)',
+        });
+    }
+    // --- input_tokens ---
+    const inputTokens = numericAttr(span.attributes, ATTR_INPUT_TOKENS);
+    if (inputTokens !== undefined) {
+        if (inputTokens >= DEFAULT_TOKEN_THRESHOLDS.inputCriticalTokens) {
+            signals.push({
+                signal: 'input_tokens',
+                severity: 'critical',
+                observed: inputTokens,
+                threshold: DEFAULT_TOKEN_THRESHOLDS.inputCriticalTokens,
+                detail: `input_tokens ${inputTokens} >= critical threshold ${DEFAULT_TOKEN_THRESHOLDS.inputCriticalTokens}`,
+            });
+        }
+        else if (inputTokens >= DEFAULT_TOKEN_THRESHOLDS.inputWarnTokens) {
+            signals.push({
+                signal: 'input_tokens',
+                severity: 'warn',
+                observed: inputTokens,
+                threshold: DEFAULT_TOKEN_THRESHOLDS.inputWarnTokens,
+                detail: `input_tokens ${inputTokens} >= warn threshold ${DEFAULT_TOKEN_THRESHOLDS.inputWarnTokens}`,
+            });
+        }
+    }
+    // --- output_tokens ---
+    const outputTokens = numericAttr(span.attributes, ATTR_OUTPUT_TOKENS);
+    if (outputTokens !== undefined) {
+        if (outputTokens >= DEFAULT_TOKEN_THRESHOLDS.outputCriticalTokens) {
+            signals.push({
+                signal: 'output_tokens',
+                severity: 'critical',
+                observed: outputTokens,
+                threshold: DEFAULT_TOKEN_THRESHOLDS.outputCriticalTokens,
+                detail: `output_tokens ${outputTokens} >= critical threshold ${DEFAULT_TOKEN_THRESHOLDS.outputCriticalTokens}`,
+            });
+        }
+        else if (outputTokens >= DEFAULT_TOKEN_THRESHOLDS.outputWarnTokens) {
+            signals.push({
+                signal: 'output_tokens',
+                severity: 'warn',
+                observed: outputTokens,
+                threshold: DEFAULT_TOKEN_THRESHOLDS.outputWarnTokens,
+                detail: `output_tokens ${outputTokens} >= warn threshold ${DEFAULT_TOKEN_THRESHOLDS.outputWarnTokens}`,
+            });
+        }
+    }
+    // --- unknown_span_name ---
+    if (category === 'unknown') {
+        signals.push({
+            signal: 'unknown_span_name',
+            severity: 'warn',
+            detail: `span name "${span.name}" does not match any known category prefix`,
+        });
+    }
+    // --- span_count ---
+    if (spansInTrace > MAX_SPANS_PER_TRACE) {
+        signals.push({
+            signal: 'span_count',
+            severity: 'warn',
+            observed: spansInTrace,
+            threshold: MAX_SPANS_PER_TRACE,
+            detail: `trace contains ${spansInTrace} spans (expected ≤ ${MAX_SPANS_PER_TRACE})`,
+        });
+    }
+    // Derive overall severity
+    const overallSeverity = signals.reduce((acc, s) => maxSeverity(acc, s.severity), 'none');
+    // Sort by severity descending
+    signals.sort((a, b) => SEVERITY_ORDER.indexOf(b.severity) - SEVERITY_ORDER.indexOf(a.severity));
+    return {
+        spanId: span.spanId,
+        traceId: span.traceId,
+        spanName: span.name,
+        category,
+        overallSeverity,
+        signals,
+        excluded,
+    };
+}
+/**
+ * Analyze an array of TraceSpan records and return per-span anomaly results.
+ * Spans with no signals fired will have overallSeverity === 'none'.
+ */
+export function detectSpanAnomalies(spans) {
+    // Build per-trace span counts for span_count signal
+    const traceSpanCounts = new Map();
+    for (const span of spans) {
+        traceSpanCounts.set(span.traceId, (traceSpanCounts.get(span.traceId) ?? 0) + 1);
+    }
+    return spans.map(span => analyzeSpan(span, traceSpanCounts.get(span.traceId) ?? 1));
+}
+/**
+ * Aggregate per-span anomaly results into a summary.
+ */
+export function buildAnomalySummary(anomalies, sessionId) {
+    const signalCounts = {};
+    let criticalCount = 0;
+    let errorCount = 0;
+    let warnCount = 0;
+    let excludedSpans = 0;
+    let anomalousSpans = 0;
+    for (const a of anomalies) {
+        if (a.excluded)
+            excludedSpans++;
+        if (a.overallSeverity !== 'none')
+            anomalousSpans++;
+        if (a.overallSeverity === 'critical')
+            criticalCount++;
+        else if (a.overallSeverity === 'error')
+            errorCount++;
+        else if (a.overallSeverity === 'warn')
+            warnCount++;
+        for (const s of a.signals) {
+            signalCounts[s.signal] = (signalCounts[s.signal] ?? 0) + 1;
+        }
+    }
+    return {
+        ...(sessionId !== undefined && { sessionId }),
+        analyzedAt: new Date().toISOString(),
+        totalSpans: anomalies.length,
+        anomalousSpans,
+        excludedSpans,
+        criticalCount,
+        errorCount,
+        warnCount,
+        signalCounts: signalCounts,
+    };
+}
+//# sourceMappingURL=trace-anomaly-detector.js.map

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

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

package/dist/lib/observability/trace-anomaly-detector.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for the INV-2 runtime anomaly detection engine.
+ */
+export {};
+//# sourceMappingURL=trace-anomaly-detector.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace-anomaly-detector.test.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/trace-anomaly-detector.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}