observability-toolkit 1.8.5 → 2.1.0

package/dist/__tests__/find-constant-dedup.test.js

@@ -0,0 +1,132 @@
+/**
+ * Tests for constant deduplication CI check
+ *
+ * Validates that check-constant-dedup.sh correctly:
+ * 1. Exits with code 0 when no duplicates found
+ * 2. Exits with code 1 when duplicates exist
+ * 3. Exits with code 42 on script errors
+ * 4. Provides helpful error messages
+ */
+import { describe, it, beforeEach, afterEach } from 'vitest';
+import * as assert from 'node:assert';
+import { execSync } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+describe('constant dedup CI check', () => {
+    let testDir;
+    const checkScriptPath = join(process.cwd(), 'scripts', 'check-constant-dedup.sh');
+    beforeEach(() => {
+        testDir = join(tmpdir(), `const-dedup-ci-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+    });
+    afterEach(() => {
+        rmSync(testDir, { recursive: true, force: true });
+    });
+    it('exits with code 0 when no duplicates found', () => {
+        // Create test directory with unique constants
+        const constantsFile = join(testDir, 'constants.ts');
+        writeFileSync(constantsFile, `
+export const TIMEOUT = 5000;
+export const MAX_ITEMS = 100;
+export const DEFAULT_SIZE = 50;
+    `);
+        try {
+            execSync(`bash ${checkScriptPath} "${testDir}" 0`);
+            assert.ok(true, 'Script exited with code 0');
+        }
+        catch (e) {
+            const error = e;
+            assert.fail(`Expected exit code 0, got ${error.status}`);
+        }
+    });
+    it('exits with code 1 when duplicates are found', () => {
+        // Create test directory with duplicate constants
+        const constantsFile = join(testDir, 'constants.ts');
+        writeFileSync(constantsFile, `
+export const VALUE = 42;
+export const VALUE = 42;
+export const OTHER = 100;
+    `);
+        let exitCode = 0;
+        try {
+            execSync(`bash ${checkScriptPath} "${testDir}" 0`, { stdio: 'pipe' });
+        }
+        catch (e) {
+            const error = e;
+            exitCode = error.status ?? 1;
+        }
+        assert.strictEqual(exitCode, 1, 'Should exit with code 1 when duplicates found');
+    });
+    it('exits with code 42 when script is not found', () => {
+        const fakePath = '/nonexistent/path/to/check-constant-dedup.sh';
+        let exitCode = 0;
+        try {
+            execSync(`bash ${fakePath} "${testDir}" 0`, { stdio: 'pipe' });
+        }
+        catch (e) {
+            const error = e;
+            exitCode = error.status ?? 1;
+        }
+        assert.ok(exitCode !== 0, 'Should exit with non-zero when script not found');
+    });
+    it('respects max_duplicates threshold', () => {
+        const constantsFile = join(testDir, 'constants.ts');
+        // Create 2 groups of duplicates
+        writeFileSync(constantsFile, `
+export const A = 1;
+export const A = 1;
+export const B = 2;
+export const B = 2;
+    `);
+        // Allow up to 2 duplicates
+        let exitCode = 0;
+        try {
+            execSync(`bash ${checkScriptPath} "${testDir}" 2`, { stdio: 'pipe' });
+        }
+        catch (e) {
+            const error = e;
+            exitCode = error.status ?? 1;
+        }
+        assert.strictEqual(exitCode, 0, 'Should exit 0 when duplicates <= max_duplicates');
+    });
+    it('fails when duplicates exceed threshold', () => {
+        const constantsFile = join(testDir, 'constants.ts');
+        // Create 3 groups of duplicates
+        writeFileSync(constantsFile, `
+export const A = 1;
+export const A = 1;
+export const B = 2;
+export const B = 2;
+export const C = 3;
+export const C = 3;
+    `);
+        // Allow only 2 duplicates
+        let exitCode = 0;
+        try {
+            execSync(`bash ${checkScriptPath} "${testDir}" 2`, { stdio: 'pipe' });
+        }
+        catch (e) {
+            const error = e;
+            exitCode = error.status ?? 1;
+        }
+        assert.strictEqual(exitCode, 1, 'Should exit 1 when duplicates > max_duplicates');
+    });
+    it('provides informative error message on failure', () => {
+        const constantsFile = join(testDir, 'constants.ts');
+        writeFileSync(constantsFile, `
+export const VALUE = 42;
+export const VALUE = 42;
+    `);
+        try {
+            execSync(`bash ${checkScriptPath} "${testDir}" 0`, { stdio: 'pipe', encoding: 'utf-8' });
+            assert.fail('Should have thrown');
+        }
+        catch (e) {
+            const error = e;
+            const output = (error.stderr || error.stdout || error.message || '').toString();
+            assert.ok(output.includes('duplicate') || output.includes('❌'), 'Error message should mention duplicates');
+        }
+    });
+});
+//# sourceMappingURL=find-constant-dedup.test.js.map

package/dist/__tests__/find-constant-dedup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-constant-dedup.test.js","sourceRoot":"","sources":["../../src/__tests__/find-constant-dedup.test.ts"],"names":[],"mappings":"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"}

package/dist/backends/backend-schemas.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Zod schemas for backend data record types.
+ *
+ * These schemas validate data at external boundaries:
+ * - JSONL telemetry files read from disk
+ * - Cloud API responses (D1, R2, API worker)
+ * - JSON-encoded span attributes (step_scores, tool_verifications)
+ *
+ * Usage:
+ *   import { traceSpanSchema } from './backend-schemas.js';
+ *   const result = traceSpanSchema.safeParse(raw);
+ */
+import { z } from 'zod';
+import { evaluatorTypeSchema } from '../lib/core/shared-schemas.js';
+export { evaluatorTypeSchema };
+export declare const instrumentationScopeSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    schemaUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export declare const spanLinkSchema: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const histogramBucketSchema: z.ZodObject<{
+    le: z.ZodNumber;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const histogramDataSchema: z.ZodObject<{
+    buckets: z.ZodArray<z.ZodObject<{
+        le: z.ZodNumber;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    sum: z.ZodNumber;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const exemplarSchema: z.ZodObject<{
+    timestamp: z.ZodISODateTime;
+    value: z.ZodNumber;
+    traceId: z.ZodOptional<z.ZodString>;
+    spanId: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const traceSpanSchema: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    parentSpanId: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        INTERNAL: "INTERNAL";
+        SERVER: "SERVER";
+        CLIENT: "CLIENT";
+        PRODUCER: "PRODUCER";
+        CONSUMER: "CONSUMER";
+    }>>;
+    startTimeUnixNano: z.ZodNumber;
+    endTimeUnixNano: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    statusCode: z.ZodOptional<z.ZodEnum<{
+        UNSET: "UNSET";
+        OK: "OK";
+        ERROR: "ERROR";
+    }>>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        timestamp: z.ZodNumber;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodString;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    instrumentationScope: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        schemaUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const logRecordSchema: z.ZodObject<{
+    timestamp: z.ZodISODateTime;
+    severity: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    severityNumber: z.ZodOptional<z.ZodNumber>;
+    body: z.ZodString;
+    traceId: z.ZodOptional<z.ZodString>;
+    spanId: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    instrumentationScope: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        schemaUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    extractedFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const metricDataPointSchema: z.ZodObject<{
+    timestamp: z.ZodISODateTime;
+    name: z.ZodString;
+    value: z.ZodNumber;
+    unit: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    histogram: z.ZodOptional<z.ZodObject<{
+        buckets: z.ZodArray<z.ZodObject<{
+            le: z.ZodNumber;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+        sum: z.ZodNumber;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    exemplars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodISODateTime;
+        value: z.ZodNumber;
+        traceId: z.ZodOptional<z.ZodString>;
+        spanId: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    aggregationTemporality: z.ZodOptional<z.ZodEnum<{
+        UNSPECIFIED: "UNSPECIFIED";
+        DELTA: "DELTA";
+        CUMULATIVE: "CUMULATIVE";
+    }>>;
+}, z.core.$strip>;
+export declare const histogramDataPointSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    count: z.ZodNumber;
+    sum: z.ZodNullable<z.ZodNumber>;
+    min: z.ZodNullable<z.ZodNumber>;
+    max: z.ZodNullable<z.ZodNumber>;
+    aggregationTemporality: z.ZodNumber;
+    explicitBounds: z.ZodArray<z.ZodNumber>;
+    bucketCounts: z.ZodArray<z.ZodNumber>;
+    timestamp: z.ZodISODateTime;
+    serviceName: z.ZodNullable<z.ZodString>;
+    sessionId: z.ZodNullable<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const llmEventSchema: z.ZodObject<{
+    timestamp: z.ZodISODateTime;
+    name: z.ZodString;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** Maximum step identifier length */
+export declare const MAX_STEP_ID_LENGTH = 256;
+export declare const stepScoreSchema: z.ZodObject<{
+    step: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    score: z.ZodNumber;
+    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    explanation: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const toolVerificationSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    toolCallId: z.ZodOptional<z.ZodString>;
+    toolCorrect: z.ZodBoolean;
+    argsCorrect: z.ZodBoolean;
+    resultCorrect: z.ZodOptional<z.ZodBoolean>;
+    score: z.ZodNumber;
+    expectedTool: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+export declare const evaluationResultSchema: z.ZodObject<{
+    timestamp: z.ZodISODateTime;
+    evaluationName: z.ZodString;
+    scoreValue: z.ZodOptional<z.ZodNumber>;
+    scoreLabel: z.ZodOptional<z.ZodString>;
+    scoreUnit: z.ZodOptional<z.ZodString>;
+    explanation: z.ZodOptional<z.ZodString>;
+    evaluator: z.ZodOptional<z.ZodString>;
+    evaluatorType: z.ZodOptional<z.ZodEnum<{
+        llm: "llm";
+        human: "human";
+        rule: "rule";
+        classifier: "classifier";
+        seed: "seed";
+        canary: "canary";
+    }>>;
+    responseId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    spanId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    agentName: z.ZodOptional<z.ZodString>;
+    stepScores: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        step: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        score: z.ZodNumber;
+        evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        explanation: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    toolVerifications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        toolName: z.ZodString;
+        toolCallId: z.ZodOptional<z.ZodString>;
+        toolCorrect: z.ZodBoolean;
+        argsCorrect: z.ZodBoolean;
+        resultCorrect: z.ZodOptional<z.ZodBoolean>;
+        score: z.ZodNumber;
+        expectedTool: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>>;
+    trajectoryLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const costDataPointSchema: z.ZodObject<{
+    model: z.ZodNullable<z.ZodString>;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    estimatedUsd: z.ZodNumber;
+}, z.core.$strip>;
+export declare const datasetFieldMappingSchema: z.ZodObject<{
+    input: z.ZodString;
+    expectedOutput: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const baseDatasetRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    frozen: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>]>;
+    traceCount: z.ZodNumber;
+    evaluationNames: z.ZodArray<z.ZodString>;
+    selectionCriteria: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    version: z.ZodOptional<z.ZodNumber>;
+    parentVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    versionCreatedAt: z.ZodOptional<z.ZodISODateTime>;
+    versionReason: z.ZodOptional<z.ZodEnum<{
+        created: "created";
+        traces_added: "traces_added";
+        traces_removed: "traces_removed";
+        metadata_updated: "metadata_updated";
+    }>>;
+    fieldMapping: z.ZodOptional<z.ZodObject<{
+        input: z.ZodString;
+        expectedOutput: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    traceSnapshot: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const datasetRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    frozen: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>]>;
+    traceCount: z.ZodNumber;
+    evaluationNames: z.ZodArray<z.ZodString>;
+    selectionCriteria: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    version: z.ZodOptional<z.ZodNumber>;
+    parentVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    versionCreatedAt: z.ZodOptional<z.ZodISODateTime>;
+    versionReason: z.ZodOptional<z.ZodEnum<{
+        created: "created";
+        traces_added: "traces_added";
+        traces_removed: "traces_removed";
+        metadata_updated: "metadata_updated";
+    }>>;
+    fieldMapping: z.ZodOptional<z.ZodObject<{
+        input: z.ZodString;
+        expectedOutput: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    traceSnapshot: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dateRangeStart: z.ZodNullable<z.ZodISODate>;
+    dateRangeEnd: z.ZodNullable<z.ZodISODate>;
+}, z.core.$strip>;
+export declare const datasetTraceRecordSchema: z.ZodObject<{
+    datasetId: z.ZodString;
+    traceId: z.ZodString;
+    addedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export declare const datasetRunRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    datasetId: z.ZodString;
+    datasetVersion: z.ZodNumber;
+    runAt: z.ZodISODateTime;
+    evaluationNames: z.ZodArray<z.ZodString>;
+    resultCount: z.ZodNumber;
+    evaluator: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InstrumentationScope = z.infer<typeof instrumentationScopeSchema>;
+export type SpanLink = z.infer<typeof spanLinkSchema>;
+export type HistogramBucket = z.infer<typeof histogramBucketSchema>;
+export type HistogramData = z.infer<typeof histogramDataSchema>;
+export type Exemplar = z.infer<typeof exemplarSchema>;
+export type { EvaluatorType } from '../lib/core/shared-schemas.js';
+export type TraceSpan = z.infer<typeof traceSpanSchema>;
+export type LogRecord = z.infer<typeof logRecordSchema>;
+export type MetricDataPoint = z.infer<typeof metricDataPointSchema>;
+export type HistogramDataPoint = z.infer<typeof histogramDataPointSchema>;
+export type LLMEvent = z.infer<typeof llmEventSchema>;
+export type StepScore = z.infer<typeof stepScoreSchema>;
+export declare function isIndexedStep(score: StepScore): score is StepScore & {
+    step: number;
+};
+export declare function isNamedStep(score: StepScore): score is StepScore & {
+    step: string;
+};
+export type ToolVerification = z.infer<typeof toolVerificationSchema>;
+export type EvaluationResult = z.infer<typeof evaluationResultSchema>;
+export type CostDataPoint = z.infer<typeof costDataPointSchema>;
+export type DatasetRecord = z.infer<typeof datasetRecordSchema>;
+export type DatasetTraceRecord = z.infer<typeof datasetTraceRecordSchema>;
+export type DatasetRunRecord = z.infer<typeof datasetRunRecordSchema>;
+export type DatasetFieldMapping = z.infer<typeof datasetFieldMappingSchema>;
+//# sourceMappingURL=backend-schemas.d.ts.map

package/dist/backends/backend-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-schemas.d.ts","sourceRoot":"","sources":["../../src/backends/backend-schemas.ts"],"names":[],"mappings":"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"}

package/dist/backends/backend-schemas.js

@@ -0,0 +1,215 @@
+/**
+ * Zod schemas for backend data record types.
+ *
+ * These schemas validate data at external boundaries:
+ * - JSONL telemetry files read from disk
+ * - Cloud API responses (D1, R2, API worker)
+ * - JSON-encoded span attributes (step_scores, tool_verifications)
+ *
+ * Usage:
+ *   import { traceSpanSchema } from './backend-schemas.js';
+ *   const result = traceSpanSchema.safeParse(raw);
+ */
+import { z } from 'zod';
+import { AgentIdSchema, evaluatorTypeSchema, modelIdSchema, normalizedScoreSchema, ResponseIdSchema, scoreUnitSchema, scoreValueSchema, severitySchema, SessionIdSchema, spanKindSchema, SpanIdSchema, TraceIdSchema } from '../lib/core/shared-schemas.js';
+// Re-export for consumers that import from backend-schemas
+export { evaluatorTypeSchema };
+// ============================================================================
+// Supporting schemas
+// ============================================================================
+export const instrumentationScopeSchema = z.object({
+    name: z.string(),
+    version: z.string().optional(),
+    schemaUrl: z.url().optional(),
+});
+export const spanLinkSchema = z.object({
+    traceId: TraceIdSchema,
+    spanId: SpanIdSchema,
+    attributes: z.record(z.string(), z.unknown()).optional(),
+});
+export const histogramBucketSchema = z.object({
+    le: z.number(),
+    count: z.number(),
+});
+export const histogramDataSchema = z.object({
+    buckets: z.array(histogramBucketSchema),
+    sum: z.number(),
+    count: z.number(),
+});
+export const exemplarSchema = z.object({
+    timestamp: z.iso.datetime(),
+    value: z.number(),
+    traceId: TraceIdSchema.optional(),
+    spanId: SpanIdSchema.optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+});
+// ============================================================================
+// Core telemetry record schemas
+// ============================================================================
+export const traceSpanSchema = z.object({
+    traceId: TraceIdSchema,
+    spanId: SpanIdSchema,
+    parentSpanId: SpanIdSchema.optional(),
+    name: z.string().min(1),
+    kind: spanKindSchema.optional(),
+    startTimeUnixNano: z.number(),
+    endTimeUnixNano: z.number().optional(),
+    durationMs: z.number().optional(),
+    status: z.object({ code: z.number(), message: z.string().optional() }).optional(),
+    statusCode: z.enum(['UNSET', 'OK', 'ERROR']).optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+    events: z.array(z.object({
+        name: z.string(),
+        timestamp: z.number(),
+        attributes: z.record(z.string(), z.unknown()).optional(),
+    })).optional(),
+    links: z.array(spanLinkSchema).optional(),
+    instrumentationScope: instrumentationScopeSchema.optional(),
+});
+export const logRecordSchema = z.object({
+    timestamp: z.iso.datetime(),
+    severity: severitySchema,
+    severityNumber: z.number().optional(),
+    body: z.string(),
+    traceId: TraceIdSchema.optional(),
+    spanId: SpanIdSchema.optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+    instrumentationScope: instrumentationScopeSchema.optional(),
+    extractedFields: z.record(z.string(), z.unknown()).optional(),
+});
+export const metricDataPointSchema = z.object({
+    timestamp: z.iso.datetime(),
+    name: z.string().min(1),
+    value: z.number(),
+    unit: z.string().optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+    histogram: histogramDataSchema.optional(),
+    exemplars: z.array(exemplarSchema).optional(),
+    aggregationTemporality: z.enum(['UNSPECIFIED', 'DELTA', 'CUMULATIVE']).optional(),
+});
+export const histogramDataPointSchema = z.object({
+    id: z.number(),
+    name: z.string().min(1),
+    count: z.number(),
+    sum: z.number().nullable(),
+    min: z.number().nullable(),
+    max: z.number().nullable(),
+    aggregationTemporality: z.number(),
+    explicitBounds: z.array(z.number()),
+    bucketCounts: z.array(z.number()),
+    timestamp: z.iso.datetime(),
+    serviceName: z.string().nullable(),
+    sessionId: SessionIdSchema.nullable(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+});
+export const llmEventSchema = z.object({
+    timestamp: z.iso.datetime(),
+    name: z.string().min(1),
+    attributes: z.record(z.string(), z.unknown()),
+});
+// ============================================================================
+// Agent-as-Judge schemas (parsed from JSON span attributes)
+// ============================================================================
+/** Maximum step identifier length */
+export const MAX_STEP_ID_LENGTH = 256;
+const evidenceSchema = z.union([
+    z.record(z.string(), z.unknown()),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+export const stepScoreSchema = z.object({
+    step: z.union([
+        z.string().max(MAX_STEP_ID_LENGTH).describe('Named step identifier'),
+        z.number().int().nonnegative().describe('Step index (non-negative integer)'),
+    ]).describe('Step identifier (index or name)'),
+    score: normalizedScoreSchema.describe('Score for this step (0-1)'),
+    evidence: evidenceSchema.optional().describe('Supporting evidence'),
+    explanation: z.string().optional().describe('Explanation for step score'),
+});
+export const toolVerificationSchema = z.object({
+    toolName: z.string().min(1).describe('Name of the tool'),
+    toolCallId: z.string().optional().describe('Tool call ID for correlation'),
+    toolCorrect: z.boolean().describe('Whether correct tool was selected'),
+    argsCorrect: z.boolean().describe('Whether arguments were correct'),
+    resultCorrect: z.boolean().optional().describe('Whether result was correct'),
+    score: normalizedScoreSchema.describe('Weighted correctness score'),
+    expectedTool: z.string().optional().describe('Expected tool if different'),
+    evidence: evidenceSchema.optional().describe('Supporting evidence'),
+});
+export const evaluationResultSchema = z.object({
+    timestamp: z.iso.datetime(),
+    evaluationName: z.string().min(1),
+    scoreValue: scoreValueSchema.optional(),
+    scoreLabel: z.string().optional(),
+    scoreUnit: scoreUnitSchema.optional(),
+    explanation: z.string().optional(),
+    evaluator: z.string().optional(),
+    evaluatorType: evaluatorTypeSchema.optional(),
+    responseId: ResponseIdSchema.optional(),
+    traceId: TraceIdSchema.optional(),
+    spanId: SpanIdSchema.optional(),
+    sessionId: SessionIdSchema.optional(),
+    agentId: AgentIdSchema.optional(),
+    agentName: z.string().optional(),
+    stepScores: z.array(stepScoreSchema).optional(),
+    toolVerifications: z.array(toolVerificationSchema).optional(),
+    trajectoryLength: z.number().optional(),
+});
+// ============================================================================
+// API response schemas
+// ============================================================================
+export const costDataPointSchema = z.object({
+    model: modelIdSchema.nullable(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    totalTokens: z.number(),
+    estimatedUsd: z.number(),
+});
+export const datasetFieldMappingSchema = z.object({
+    input: z.string(),
+    expectedOutput: z.string().optional(),
+    metadata: z.array(z.string()).optional(),
+});
+export const baseDatasetRecordSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    createdAt: z.iso.datetime(),
+    frozen: z.union([z.literal(0), z.literal(1)]),
+    traceCount: z.number(),
+    evaluationNames: z.array(z.string()),
+    selectionCriteria: z.record(z.string(), z.unknown()).nullable(),
+    version: z.number().optional(),
+    parentVersion: z.number().nullable().optional(),
+    versionCreatedAt: z.iso.datetime().optional(),
+    versionReason: z.enum(['created', 'traces_added', 'traces_removed', 'metadata_updated']).optional(),
+    fieldMapping: datasetFieldMappingSchema.optional(),
+    traceSnapshot: z.array(z.string()).optional(),
+});
+export const datasetRecordSchema = baseDatasetRecordSchema.extend({
+    dateRangeStart: z.iso.date().nullable(),
+    dateRangeEnd: z.iso.date().nullable(),
+});
+export const datasetTraceRecordSchema = z.object({
+    datasetId: z.string(),
+    traceId: TraceIdSchema,
+    addedAt: z.iso.datetime(),
+});
+export const datasetRunRecordSchema = z.object({
+    id: z.string(),
+    datasetId: z.string(),
+    datasetVersion: z.number(),
+    runAt: z.iso.datetime(),
+    evaluationNames: z.array(z.string()),
+    resultCount: z.number(),
+    evaluator: z.string().optional(),
+});
+export function isIndexedStep(score) {
+    return typeof score.step === 'number';
+}
+export function isNamedStep(score) {
+    return typeof score.step === 'string';
+}
+//# sourceMappingURL=backend-schemas.js.map