observability-toolkit 2.0.0 → 2.1.1

package/dist/lib/judge/evaluation-hooks.test.js

@@ -0,0 +1,934 @@
+/**
+ * Tests for evaluation-hooks.ts
+ *
+ * Covers: HMAC signature validation, payload validation, JSONL conversion,
+ * single/batch processing, and edge cases.
+ */
+import { describe, it, beforeEach, afterEach } from 'vitest';
+import assert from 'node:assert';
+import { createHmac } from 'crypto';
+import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { verifyHmacSignature, validateEvaluationPayload, payloadToJsonlRecord, processEvaluation, processBatch, resetHookStats, getHookStats, persistHookStats, loadPersistedHookStats, loadWebhookConfigs, saveWebhookConfig, deleteWebhookConfig, isValidWebhookConfig, DEFAULT_BATCH_SIZE, MAX_BATCH_BYTES, MAX_SINGLE_EVALUATION_BYTES, } from './evaluation-hooks.js';
+import { normalizeScore, SCORE_UNIT_CONFIGS, webhookEvaluationPayloadSchema, } from './evaluation-hooks-schemas.js';
+import { NORMALIZED_SCORE_MAX, NORMALIZED_SCORE_MIN, } from './llm-judge-constants.js';
+import { HOOK_RESPONSE_TEXT_LENGTH, MAX_NAME_LENGTH, SHA256_HEX_LENGTH } from '../core/constants.js';
+import { PROBABILITY_FIFTY_PERCENT, PROBABILITY_NINETY_PERCENT, SAMPLE_SIZE_100, COUNT_FIVE, COUNT_THREE, COUNT_THIRTY, COUNT_TEN, COUNT_TWO, COUNT_FIFTY, RANDOM_STRING_RADIX, RANDOM_SUFFIX_START, VALUE_FORTY_TWO, } from '../../test-helpers/test-constants.js';
+import { TEST_SCORE_BASELINE, TEST_SCORE_GOOD, TEST_SCORE_HIGH, TEST_SCORE_PASSING, TEST_SCORE_STRONG, } from '../quality/quality-test-constants.js';
+const TEST_SCORE_ABOVE_MAX = 1.5;
+const TEST_SCORE_BELOW_MIN = -0.5;
+const TEST_SCORE_EPSILON = 0.0000001;
+const TEST_SCORE_NEAR_MAX = 0.9999999;
+const LARGE_BATCH_METADATA_BYTES = 50_000;
+const BATCH_EVALUATION_COUNT_EXCESSIVE = COUNT_THIRTY;
+const WEBHOOK_VALIDATION_INDEX = COUNT_FIVE;
+// Test helper for creating temp directories
+function createTempDir() {
+    const dir = join(tmpdir(), `eval-hooks-test-${Date.now()}-${Math.random().toString(RANDOM_STRING_RADIX).slice(RANDOM_SUFFIX_START)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function removeTempDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+describe('evaluation-hooks', () => {
+    describe('verifyHmacSignature', () => {
+        const secret = 'test-secret-key';
+        const payload = `{"evaluationName":"test","scoreValue":${TEST_SCORE_GOOD}}`;
+        function generateSignature(data, key) {
+            return 'sha256=' + createHmac('sha256', key).update(data).digest('hex');
+        }
+        it('should verify valid HMAC signature', () => {
+            const signature = generateSignature(payload, secret);
+            const result = verifyHmacSignature(payload, signature, secret);
+            assert.strictEqual(result.valid, true);
+            assert.strictEqual(result.algorithm, 'sha256');
+        });
+        it('should reject missing signature', () => {
+            const result = verifyHmacSignature(payload, '', secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes('Missing signature'));
+        });
+        it('should reject invalid signature format', () => {
+            const result = verifyHmacSignature(payload, 'invalid-format', secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes('Invalid signature format'));
+        });
+        it('should reject signature without sha256= prefix', () => {
+            const hex = createHmac('sha256', secret).update(payload).digest('hex');
+            const result = verifyHmacSignature(payload, hex, secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes('Invalid signature format'));
+        });
+        it('should reject signature with wrong hex length', () => {
+            const result = verifyHmacSignature(payload, 'sha256=abc123', secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes(`expected ${SHA256_HEX_LENGTH} hex chars`));
+        });
+        it('should reject signature with non-hex characters', () => {
+            const result = verifyHmacSignature(payload, 'sha256=' + 'g'.repeat(SHA256_HEX_LENGTH), secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes(`expected ${SHA256_HEX_LENGTH} hex chars`));
+        });
+        it('should reject signature mismatch (wrong secret)', () => {
+            const signature = generateSignature(payload, 'wrong-secret');
+            const result = verifyHmacSignature(payload, signature, secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes('Signature mismatch'));
+        });
+        it('should reject signature mismatch (modified payload)', () => {
+            const signature = generateSignature(payload, secret);
+            const result = verifyHmacSignature('modified-payload', signature, secret);
+            assert.strictEqual(result.valid, false);
+            assert.ok(result.error?.includes('Signature mismatch'));
+        });
+        it('should track signature failures in stats', () => {
+            resetHookStats();
+            const badSignature = 'sha256=' + 'a'.repeat(SHA256_HEX_LENGTH);
+            verifyHmacSignature(payload, badSignature, secret);
+            const stats = getHookStats();
+            assert.strictEqual(stats.signatureFailures, 1);
+        });
+        it('should handle empty payload', () => {
+            const emptyPayload = '';
+            const signature = generateSignature(emptyPayload, secret);
+            const result = verifyHmacSignature(emptyPayload, signature, secret);
+            assert.strictEqual(result.valid, true);
+        });
+        it('should handle unicode payload', () => {
+            const unicodePayload = '{"text":"hello \ud83d\ude00 world"}';
+            const signature = generateSignature(unicodePayload, secret);
+            const result = verifyHmacSignature(unicodePayload, signature, secret);
+            assert.strictEqual(result.valid, true);
+        });
+    });
+    describe('validateEvaluationPayload', () => {
+        const validPayload = {
+            evaluationName: 'relevance',
+            scoreValue: TEST_SCORE_STRONG,
+            evaluator: 'claude-3-sonnet',
+            evaluatorType: 'llm',
+        };
+        it('should accept valid payload', () => {
+            const errors = validateEvaluationPayload(validPayload);
+            assert.strictEqual(errors.length, 0);
+        });
+        it('should require evaluationName', () => {
+            const payload = { ...validPayload, evaluationName: '' };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'evaluationName'));
+        });
+        it('should require evaluator', () => {
+            const payload = { ...validPayload, evaluator: '' };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'evaluator'));
+        });
+        it('should require evaluatorType', () => {
+            const payload = { ...validPayload, evaluatorType: 'invalid' };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'evaluatorType'));
+        });
+        it('should require scoreValue or scoreLabel', () => {
+            const payload = { ...validPayload, scoreValue: undefined, scoreLabel: undefined };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'scoreValue/scoreLabel'));
+        });
+        it('should accept scoreLabel without scoreValue', () => {
+            const payload = { ...validPayload, scoreValue: undefined, scoreLabel: 'pass' };
+            const errors = validateEvaluationPayload(payload);
+            assert.strictEqual(errors.length, 0);
+        });
+        it('should reject non-finite scoreValue at schema level', () => {
+            const result = webhookEvaluationPayloadSchema.safeParse({ ...validPayload, scoreValue: NaN });
+            assert.strictEqual(result.success, false);
+        });
+        it('should reject Infinity scoreValue at schema level', () => {
+            const result = webhookEvaluationPayloadSchema.safeParse({ ...validPayload, scoreValue: Infinity });
+            assert.strictEqual(result.success, false);
+        });
+        it('should reject oversized evaluationName', () => {
+            const payload = { ...validPayload, evaluationName: 'x'.repeat(MAX_NAME_LENGTH + 1) };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'evaluationName' && e.message.includes('maximum length')));
+        });
+        it('should reject oversized explanation', () => {
+            const payload = { ...validPayload, explanation: 'x'.repeat(HOOK_RESPONSE_TEXT_LENGTH + 1) };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'explanation'));
+        });
+        it('should validate stepScores structure', () => {
+            const payload = {
+                ...validPayload,
+                stepScores: [{ step: 'invalid' }], // Missing score
+            };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field.includes('stepScores')));
+        });
+        it('should accept valid stepScores', () => {
+            const payload = {
+                ...validPayload,
+                stepScores: [
+                    { step: 0, score: TEST_SCORE_HIGH },
+                    { step: 'reasoning', score: TEST_SCORE_GOOD },
+                ],
+            };
+            const errors = validateEvaluationPayload(payload);
+            assert.strictEqual(errors.length, 0);
+        });
+        it('should validate toolVerifications structure', () => {
+            const payload = {
+                ...validPayload,
+                toolVerifications: [{ toolName: 'test' }], // Missing required fields
+            };
+            const errors = validateEvaluationPayload(payload);
+            const tvError = errors.find(e => e.field.includes('toolVerifications'));
+            assert.ok(tvError, 'Expected a toolVerifications validation error');
+            assert.match(tvError.message, /Invalid tool verification: .*expected boolean/);
+        });
+        it('should accept valid toolVerifications', () => {
+            const payload = {
+                ...validPayload,
+                toolVerifications: [
+                    { toolName: 'search', toolCorrect: true, argsCorrect: true, score: 1.0 },
+                ],
+            };
+            const errors = validateEvaluationPayload(payload);
+            assert.strictEqual(errors.length, 0);
+        });
+        it('should reject negative trajectoryLength', () => {
+            const payload = { ...validPayload, trajectoryLength: -1 };
+            const errors = validateEvaluationPayload(payload);
+            assert.ok(errors.some(e => e.field === 'trajectoryLength'));
+        });
+        it('should include index in batch validation', () => {
+            const errors = validateEvaluationPayload({ ...validPayload, evaluationName: '' }, WEBHOOK_VALIDATION_INDEX);
+            assert.ok(errors.some(e => e.index === WEBHOOK_VALIDATION_INDEX));
+        });
+        it('should reject oversized payload', () => {
+            const largePayload = {
+                ...validPayload,
+                metadata: { data: 'x'.repeat(MAX_SINGLE_EVALUATION_BYTES) },
+            };
+            const errors = validateEvaluationPayload(largePayload);
+            assert.ok(errors.some(e => e.field === 'payload' && e.message.includes('exceeds maximum')));
+        });
+    });
+    describe('normalizeScore', () => {
+        it('should clamp ratio_0_1 to 0-1', () => {
+            assert.strictEqual(normalizeScore(PROBABILITY_FIFTY_PERCENT), PROBABILITY_FIFTY_PERCENT);
+            assert.strictEqual(normalizeScore(TEST_SCORE_BELOW_MIN), NORMALIZED_SCORE_MIN);
+            assert.strictEqual(normalizeScore(TEST_SCORE_ABOVE_MAX), NORMALIZED_SCORE_MAX);
+        });
+        it('should handle undefined unit', () => {
+            assert.strictEqual(normalizeScore(TEST_SCORE_PASSING, undefined), TEST_SCORE_PASSING);
+        });
+        it('should convert percentage to 0-1', () => {
+            assert.strictEqual(normalizeScore(COUNT_FIFTY, 'percentage'), PROBABILITY_FIFTY_PERCENT);
+            assert.strictEqual(normalizeScore(SAMPLE_SIZE_100, 'percentage'), NORMALIZED_SCORE_MAX);
+            assert.strictEqual(normalizeScore(NORMALIZED_SCORE_MIN, 'percentage'), NORMALIZED_SCORE_MIN);
+        });
+        it('should convert stars_5 to 0-1', () => {
+            assert.strictEqual(normalizeScore(SCORE_UNIT_CONFIGS.stars_5.inputMax, 'stars_5'), NORMALIZED_SCORE_MAX);
+            assert.strictEqual(normalizeScore(NORMALIZED_SCORE_MIN, 'stars_5'), NORMALIZED_SCORE_MIN);
+            assert.strictEqual(normalizeScore(SCORE_UNIT_CONFIGS.stars_5.inputMax / COUNT_TWO, 'stars_5'), PROBABILITY_FIFTY_PERCENT);
+        });
+        it('should convert likert_5 to 0-1', () => {
+            assert.strictEqual(normalizeScore(SCORE_UNIT_CONFIGS.likert_5.inputMax, 'likert_5'), NORMALIZED_SCORE_MAX);
+            assert.strictEqual(normalizeScore(SCORE_UNIT_CONFIGS.likert_5.inputMin, 'likert_5'), NORMALIZED_SCORE_MIN);
+            assert.strictEqual(normalizeScore(COUNT_THREE, 'likert_5'), PROBABILITY_FIFTY_PERCENT);
+        });
+        it('should handle unknown unit as ratio_0_1', () => {
+            assert.strictEqual(normalizeScore(TEST_SCORE_BASELINE, 'unknown_unit'), TEST_SCORE_BASELINE);
+        });
+        it('should handle NaN', () => {
+            assert.strictEqual(normalizeScore(NaN), NORMALIZED_SCORE_MIN);
+        });
+        it('should handle Infinity', () => {
+            assert.strictEqual(normalizeScore(Infinity), NORMALIZED_SCORE_MIN);
+            assert.strictEqual(normalizeScore(-Infinity), NORMALIZED_SCORE_MIN);
+        });
+    });
+    describe('payloadToJsonlRecord', () => {
+        const payload = {
+            evaluationName: 'relevance',
+            scoreValue: TEST_SCORE_STRONG,
+            scoreLabel: 'pass',
+            evaluator: 'claude-3-sonnet',
+            evaluatorType: 'llm',
+            explanation: 'Response is relevant',
+        };
+        it('should create valid JSON record', () => {
+            const record = payloadToJsonlRecord(payload);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.name, 'gen_ai.evaluation.result');
+            assert.ok(parsed.timestamp);
+            assert.ok(parsed.attributes);
+        });
+        it('should include all standard attributes', () => {
+            const record = payloadToJsonlRecord(payload);
+            const parsed = JSON.parse(record);
+            const attrs = parsed.attributes;
+            assert.strictEqual(attrs['gen_ai.evaluation.name'], 'relevance');
+            assert.strictEqual(attrs['gen_ai.evaluation.score.value'], TEST_SCORE_STRONG);
+            assert.strictEqual(attrs['gen_ai.evaluation.score.label'], 'pass');
+            assert.strictEqual(attrs['gen_ai.evaluation.evaluator'], 'claude-3-sonnet');
+            assert.strictEqual(attrs['gen_ai.evaluation.evaluator.type'], 'llm');
+            assert.strictEqual(attrs['gen_ai.evaluation.explanation'], 'Response is relevant');
+        });
+        it('should use provided timestamp', () => {
+            const ts = '2026-01-01T00:00:00.000Z';
+            const record = payloadToJsonlRecord(payload, ts);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.timestamp, ts);
+        });
+        it('should include traceId when provided', () => {
+            const payloadWithTrace = { ...payload, traceId: 'abc123' };
+            const record = payloadToJsonlRecord(payloadWithTrace);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.traceId, 'abc123');
+        });
+        it('should include sessionId in attributes', () => {
+            const payloadWithSession = { ...payload, sessionId: 'sess-123' };
+            const record = payloadToJsonlRecord(payloadWithSession);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.attributes['session.id'], 'sess-123');
+        });
+        it('should include Agent-as-Judge fields', () => {
+            const agentPayload = {
+                ...payload,
+                agentId: 'agent-1',
+                agentName: 'TestAgent',
+                stepScores: [{ step: NORMALIZED_SCORE_MIN, score: PROBABILITY_NINETY_PERCENT }],
+                toolVerifications: [{ toolName: 'search', toolCorrect: true, argsCorrect: true, score: NORMALIZED_SCORE_MAX }],
+                trajectoryLength: COUNT_FIVE,
+            };
+            const record = payloadToJsonlRecord(agentPayload);
+            const parsed = JSON.parse(record);
+            const attrs = parsed.attributes;
+            assert.strictEqual(attrs['gen_ai.agent.id'], 'agent-1');
+            assert.strictEqual(attrs['gen_ai.agent.name'], 'TestAgent');
+            assert.ok(attrs['gen_ai.evaluation.step_scores']);
+            assert.ok(attrs['gen_ai.evaluation.tool_verifications']);
+            assert.strictEqual(attrs['gen_ai.evaluation.trajectory_length'], COUNT_FIVE);
+        });
+        it('should normalize score based on unit', () => {
+            const percentagePayload = {
+                ...payload,
+                scoreValue: TEST_SCORE_STRONG * SAMPLE_SIZE_100,
+                scoreUnit: 'percentage',
+            };
+            const record = payloadToJsonlRecord(percentagePayload);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.attributes['gen_ai.evaluation.score.value'], TEST_SCORE_STRONG);
+        });
+        it('should prefix custom metadata', () => {
+            const payloadWithMeta = {
+                ...payload,
+                metadata: { custom_field: 'value', number: VALUE_FORTY_TWO },
+            };
+            const record = payloadToJsonlRecord(payloadWithMeta);
+            const parsed = JSON.parse(record);
+            assert.strictEqual(parsed.attributes['webhook.metadata.custom_field'], 'value');
+            assert.strictEqual(parsed.attributes['webhook.metadata.number'], VALUE_FORTY_TWO);
+        });
+    });
+    describe('processEvaluation', () => {
+        let tempDir;
+        let options;
+        beforeEach(() => {
+            tempDir = createTempDir();
+            options = { telemetryDir: tempDir };
+            resetHookStats();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        const validPayload = {
+            evaluationName: 'relevance',
+            scoreValue: TEST_SCORE_STRONG,
+            evaluator: 'claude-3-sonnet',
+            evaluatorType: 'llm',
+        };
+        it('should write evaluation to JSONL file', async () => {
+            const result = await processEvaluation(validPayload, options);
+            assert.strictEqual(result.success, true);
+            assert.strictEqual(result.processedCount, 1);
+            // Verify file was written
+            const files = readdirSync(tempDir);
+            assert.ok(files.some((f) => f.startsWith('evaluations-') && f.endsWith('.jsonl')));
+        });
+        it('should return validation errors for invalid payload', async () => {
+            const invalidPayload = { ...validPayload, evaluationName: '' };
+            const result = await processEvaluation(invalidPayload, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.message.includes('Validation failed'));
+            assert.ok(result.errors && result.errors.length > 0);
+        });
+        it('should create telemetry directory if it does not exist', async () => {
+            const newDir = join(tempDir, 'nested', 'dir');
+            const newOptions = { telemetryDir: newDir };
+            await processEvaluation(validPayload, newOptions);
+            assert.ok(existsSync(newDir));
+        });
+        it('should update hook stats on success', async () => {
+            await processEvaluation(validPayload, options);
+            const stats = getHookStats();
+            assert.strictEqual(stats.totalReceived, 1);
+            assert.strictEqual(stats.successCount, 1);
+            assert.ok(stats.lastProcessedAt);
+        });
+        it('should update hook stats on validation failure', async () => {
+            const invalidPayload = { ...validPayload, evaluationName: '' };
+            await processEvaluation(invalidPayload, options);
+            const stats = getHookStats();
+            assert.strictEqual(stats.totalReceived, 1);
+            assert.strictEqual(stats.validationFailures, 1);
+        });
+        it('should write valid JSONL content', async () => {
+            await processEvaluation(validPayload, options);
+            const files = readdirSync(tempDir);
+            const evalFile = files.find((f) => f.startsWith('evaluations-'));
+            assert.ok(evalFile, 'Evaluations file should exist');
+            const content = readFileSync(join(tempDir, evalFile), 'utf-8');
+            const lines = content.trim().split('\n');
+            assert.strictEqual(lines.length, 1);
+            const record = JSON.parse(lines[0]);
+            assert.strictEqual(record.name, 'gen_ai.evaluation.result');
+            assert.strictEqual(record.attributes['gen_ai.evaluation.name'], 'relevance');
+        });
+    });
+    describe('processBatch', () => {
+        let tempDir;
+        let options;
+        beforeEach(() => {
+            tempDir = createTempDir();
+            options = { telemetryDir: tempDir };
+            resetHookStats();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        const validPayload = {
+            evaluationName: 'relevance',
+            scoreValue: TEST_SCORE_STRONG,
+            evaluator: 'claude-3-sonnet',
+            evaluatorType: 'llm',
+        };
+        it('should process batch of evaluations', async () => {
+            const batch = {
+                evaluations: [
+                    { ...validPayload, evaluationName: 'relevance' },
+                    { ...validPayload, evaluationName: 'faithfulness' },
+                    { ...validPayload, evaluationName: 'coherence' },
+                ],
+            };
+            const result = await processBatch(batch, options);
+            assert.strictEqual(result.success, true);
+            assert.strictEqual(result.processedCount, COUNT_THREE);
+        });
+        it('should reject empty batch', async () => {
+            const result = await processBatch({ evaluations: [] }, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.message.includes('Empty batch'));
+        });
+        it('should reject batch exceeding size limit', async () => {
+            const batch = {
+                evaluations: Array(DEFAULT_BATCH_SIZE + 1).fill(validPayload),
+            };
+            const result = await processBatch(batch, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.message.includes('Batch too large'));
+        });
+        it('should reject batch if any evaluation fails validation', async () => {
+            const batch = {
+                evaluations: [
+                    validPayload,
+                    { ...validPayload, evaluationName: '' }, // Invalid
+                    validPayload,
+                ],
+            };
+            const result = await processBatch(batch, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.errors && result.errors.length > 0);
+        });
+        it('should include indices in validation errors', async () => {
+            const batch = {
+                evaluations: [
+                    validPayload,
+                    { ...validPayload, evaluationName: '' }, // Invalid at index 1
+                ],
+            };
+            const result = await processBatch(batch, options);
+            assert.ok(result.errors?.some((e) => e.index === 1));
+        });
+        it('should write all evaluations to same file', async () => {
+            const batch = {
+                evaluations: [
+                    { ...validPayload, evaluationName: 'eval1' },
+                    { ...validPayload, evaluationName: 'eval2' },
+                ],
+            };
+            await processBatch(batch, options);
+            const files = readdirSync(tempDir);
+            const evalFile = files.find((f) => f.startsWith('evaluations-'));
+            assert.ok(evalFile, 'Evaluations file should exist');
+            const content = readFileSync(join(tempDir, evalFile), 'utf-8');
+            const lines = content.trim().split('\n');
+            assert.strictEqual(lines.length, COUNT_TWO);
+        });
+        it('should reject batch exceeding byte size limit', async () => {
+            // Create payload that will exceed byte limit
+            const largeMetadata = { data: 'x'.repeat(LARGE_BATCH_METADATA_BYTES) };
+            const batch = {
+                evaluations: Array(BATCH_EVALUATION_COUNT_EXCESSIVE).fill({
+                    ...validPayload,
+                    metadata: largeMetadata,
+                }),
+            };
+            const result = await processBatch(batch, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.message.includes('too large') || result.message.includes('exceeds maximum'));
+        });
+        it('should update hook stats for batch', async () => {
+            const batch = { evaluations: [validPayload, validPayload, validPayload] };
+            await processBatch(batch, options);
+            const stats = getHookStats();
+            assert.strictEqual(stats.totalReceived, COUNT_THREE);
+            assert.strictEqual(stats.successCount, COUNT_THREE);
+        });
+        it('should reject invalid evaluations array', async () => {
+            const result = await processBatch({ evaluations: 'not an array' }, options);
+            assert.strictEqual(result.success, false);
+            assert.ok(result.message.includes('must be an array'));
+        });
+    });
+    describe('resetHookStats', () => {
+        it('should reset all stats to zero', async () => {
+            const tempDir = createTempDir();
+            const options = { telemetryDir: tempDir };
+            const validPayload = {
+                evaluationName: 'test',
+                scoreValue: PROBABILITY_FIFTY_PERCENT,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+            };
+            // Generate some stats
+            await processEvaluation(validPayload, options);
+            resetHookStats();
+            const stats = getHookStats();
+            assert.strictEqual(stats.totalReceived, 0);
+            assert.strictEqual(stats.successCount, 0);
+            assert.strictEqual(stats.validationFailures, 0);
+            assert.strictEqual(stats.signatureFailures, 0);
+            assert.strictEqual(stats.deduplicatedCount, 0);
+            removeTempDir(tempDir);
+        });
+    });
+    describe('constants', () => {
+        it('should export DEFAULT_BATCH_SIZE', () => {
+            assert.strictEqual(typeof DEFAULT_BATCH_SIZE, 'number');
+            assert.ok(DEFAULT_BATCH_SIZE > 0);
+        });
+        it('should export MAX_BATCH_BYTES', () => {
+            assert.strictEqual(typeof MAX_BATCH_BYTES, 'number');
+            assert.ok(MAX_BATCH_BYTES > 0);
+        });
+        it('should export MAX_SINGLE_EVALUATION_BYTES', () => {
+            assert.strictEqual(typeof MAX_SINGLE_EVALUATION_BYTES, 'number');
+            assert.ok(MAX_SINGLE_EVALUATION_BYTES > 0);
+        });
+    });
+    describe('edge cases', () => {
+        let tempDir;
+        let options;
+        beforeEach(() => {
+            tempDir = createTempDir();
+            options = { telemetryDir: tempDir };
+            resetHookStats();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        it('should handle unicode in evaluation names', async () => {
+            const payload = {
+                evaluationName: 'test-\u65e5\u672c\u8a9e',
+                scoreValue: TEST_SCORE_GOOD,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+            };
+            const result = await processEvaluation(payload, options);
+            assert.strictEqual(result.success, true);
+        });
+        it('should handle special characters in explanation', async () => {
+            const payload = {
+                evaluationName: 'test',
+                scoreValue: TEST_SCORE_GOOD,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+                explanation: 'Line1\nLine2\tTabbed"Quoted"\'Single\'',
+            };
+            const result = await processEvaluation(payload, options);
+            assert.strictEqual(result.success, true);
+        });
+        it('should handle boundary score values', async () => {
+            const payloads = [
+                { ...createPayload(), scoreValue: NORMALIZED_SCORE_MIN },
+                { ...createPayload(), scoreValue: NORMALIZED_SCORE_MAX },
+                { ...createPayload(), scoreValue: TEST_SCORE_EPSILON },
+                { ...createPayload(), scoreValue: TEST_SCORE_NEAR_MAX },
+            ];
+            for (const payload of payloads) {
+                const result = await processEvaluation(payload, options);
+                assert.strictEqual(result.success, true);
+            }
+        });
+        it('should handle concurrent writes', async () => {
+            const payload = {
+                evaluationName: 'test',
+                scoreValue: TEST_SCORE_GOOD,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+            };
+            // Write 10 evaluations concurrently
+            const promises = Array(COUNT_TEN).fill(null).map(() => processEvaluation(payload, options));
+            const results = await Promise.all(promises);
+            assert.ok(results.every(r => r.success));
+            // Verify all were written
+            const files = readdirSync(tempDir);
+            const evalFile = files.find((f) => f.startsWith('evaluations-'));
+            assert.ok(evalFile, 'Evaluations file should exist');
+            const content = readFileSync(join(tempDir, evalFile), 'utf-8');
+            const lines = content.trim().split('\n');
+            assert.strictEqual(lines.length, COUNT_TEN);
+        });
+    });
+    describe('deduplication', () => {
+        let tempDir;
+        let options;
+        beforeEach(() => {
+            tempDir = createTempDir();
+            options = { telemetryDir: tempDir, deduplication: true };
+            resetHookStats();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        it('should skip duplicate evaluations with same responseId + evaluationName', async () => {
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'claude-3-sonnet',
+                evaluatorType: 'llm',
+                responseId: 'resp-001',
+            };
+            const result1 = await processEvaluation(payload, options);
+            const result2 = await processEvaluation(payload, options);
+            assert.strictEqual(result1.success, true);
+            assert.strictEqual(result1.processedCount, 1);
+            assert.strictEqual(result2.success, true);
+            assert.strictEqual(result2.processedCount, 0);
+            assert.ok(result2.message.includes('Duplicate'));
+            const stats = getHookStats();
+            assert.strictEqual(stats.successCount, 1);
+            assert.strictEqual(stats.deduplicatedCount, 1);
+        });
+        it('should allow different evaluationNames for same responseId', async () => {
+            const base = {
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'claude-3-sonnet',
+                evaluatorType: 'llm',
+                responseId: 'resp-001',
+            };
+            const r1 = await processEvaluation({ ...base, evaluationName: 'relevance' }, options);
+            const r2 = await processEvaluation({ ...base, evaluationName: 'coherence' }, options);
+            assert.strictEqual(r1.processedCount, 1);
+            assert.strictEqual(r2.processedCount, 1);
+            assert.strictEqual(getHookStats().deduplicatedCount, 0);
+        });
+        it('should not deduplicate when responseId is missing', async () => {
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+            };
+            const r1 = await processEvaluation(payload, options);
+            const r2 = await processEvaluation(payload, options);
+            assert.strictEqual(r1.processedCount, 1);
+            assert.strictEqual(r2.processedCount, 1);
+            assert.strictEqual(getHookStats().deduplicatedCount, 0);
+        });
+        it('should not deduplicate when deduplication is disabled', async () => {
+            const noDedup = { telemetryDir: tempDir, deduplication: false };
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+                responseId: 'resp-001',
+            };
+            const r1 = await processEvaluation(payload, noDedup);
+            const r2 = await processEvaluation(payload, noDedup);
+            assert.strictEqual(r1.processedCount, 1);
+            assert.strictEqual(r2.processedCount, 1);
+        });
+        it('should deduplicate within batch', async () => {
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+                responseId: 'resp-batch-001',
+            };
+            const batch = {
+                evaluations: [payload, payload, { ...payload, evaluationName: 'coherence' }],
+            };
+            const result = await processBatch(batch, options);
+            assert.strictEqual(result.success, true);
+            assert.strictEqual(result.processedCount, COUNT_TWO);
+            assert.ok(result.message.includes('1 duplicate'));
+            assert.strictEqual(getHookStats().deduplicatedCount, 1);
+        });
+        it('should deduplicate across single and batch calls', async () => {
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+                responseId: 'resp-cross-001',
+            };
+            await processEvaluation(payload, options);
+            const batchResult = await processBatch({ evaluations: [payload] }, options);
+            assert.strictEqual(batchResult.processedCount, 0);
+            assert.strictEqual(getHookStats().deduplicatedCount, 1);
+        });
+        it('should handle all-deduplicated batch without writing file', async () => {
+            const payload = {
+                evaluationName: 'relevance',
+                scoreValue: TEST_SCORE_STRONG,
+                evaluator: 'test',
+                evaluatorType: 'llm',
+                responseId: 'resp-alldedup-001',
+            };
+            await processEvaluation(payload, options);
+            const batchResult = await processBatch({ evaluations: [payload, payload] }, options);
+            assert.strictEqual(batchResult.success, true);
+            assert.strictEqual(batchResult.processedCount, 0);
+            assert.strictEqual(getHookStats().deduplicatedCount, COUNT_TWO);
+        });
+    });
+    function createPayload() {
+        return {
+            evaluationName: 'test',
+            scoreValue: PROBABILITY_FIFTY_PERCENT,
+            evaluator: 'test',
+            evaluatorType: 'llm',
+        };
+    }
+    describe('persistHookStats / loadPersistedHookStats', () => {
+        let tempDir;
+        beforeEach(() => {
+            tempDir = createTempDir();
+            resetHookStats();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        it('should persist and restore stats', async () => {
+            const options = { telemetryDir: tempDir };
+            const payload = createPayload();
+            await processEvaluation(payload, options);
+            const statsFile = join(tempDir, 'hook-stats.json');
+            await persistHookStats(statsFile);
+            resetHookStats();
+            assert.strictEqual(getHookStats().successCount, 0);
+            await loadPersistedHookStats(statsFile);
+            const restored = getHookStats();
+            assert.strictEqual(restored.totalReceived, 1);
+            assert.strictEqual(restored.successCount, 1);
+            assert.ok(restored.lastProcessedAt);
+        });
+        it('should silently ignore missing stats file', async () => {
+            await loadPersistedHookStats(join(tempDir, 'nonexistent.json'));
+            assert.strictEqual(getHookStats().successCount, 0);
+        });
+        it('should silently ignore malformed stats file', async () => {
+            const statsFile = join(tempDir, 'hook-stats.json');
+            writeFileSync(statsFile, 'not-json', 'utf-8');
+            await loadPersistedHookStats(statsFile);
+            assert.strictEqual(getHookStats().successCount, 0);
+        });
+        it('should replace in-memory stats on load (not additive)', async () => {
+            const options = { telemetryDir: tempDir };
+            // Process one, save state
+            await processEvaluation(createPayload(), options);
+            const statsFile = join(tempDir, 'hook-stats.json');
+            await persistHookStats(statsFile);
+            // Process two more (state now has 3), then reload the saved state
+            await processEvaluation(createPayload(), options);
+            await processEvaluation(createPayload(), options);
+            assert.strictEqual(getHookStats().successCount, COUNT_THREE);
+            await loadPersistedHookStats(statsFile);
+            assert.strictEqual(getHookStats().successCount, 1);
+        });
+    });
+    describe('webhook config persistence', () => {
+        let tempDir;
+        beforeEach(() => {
+            tempDir = createTempDir();
+        });
+        afterEach(() => {
+            removeTempDir(tempDir);
+        });
+        function makeConfig(id) {
+            return {
+                id,
+                name: `Webhook ${id}`,
+                authMethod: 'hmac-sha256',
+                secret: 'test-secret',
+                enabled: true,
+                createdAt: '2026-01-01T00:00:00.000Z',
+            };
+        }
+        it('should return empty array for missing config file', async () => {
+            const configs = await loadWebhookConfigs(join(tempDir, 'nonexistent.json'));
+            assert.deepStrictEqual(configs, []);
+        });
+        it('should return empty array for malformed config file', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            writeFileSync(configFile, 'not-json', 'utf-8');
+            const configs = await loadWebhookConfigs(configFile);
+            assert.deepStrictEqual(configs, []);
+        });
+        it('should save and load a single config', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            const config = makeConfig('wh-001');
+            await saveWebhookConfig(config, configFile);
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, 1);
+            assert.strictEqual(loaded[0].id, 'wh-001');
+            assert.strictEqual(loaded[0].secret, 'test-secret');
+        });
+        it('should upsert existing config by id', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            const config = makeConfig('wh-001');
+            await saveWebhookConfig(config, configFile);
+            await saveWebhookConfig({ ...config, name: 'Updated', enabled: false }, configFile);
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, 1);
+            assert.strictEqual(loaded[0].name, 'Updated');
+            assert.strictEqual(loaded[0].enabled, false);
+        });
+        it('should save multiple configs independently', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            await saveWebhookConfig(makeConfig('wh-001'), configFile);
+            await saveWebhookConfig(makeConfig('wh-002'), configFile);
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, COUNT_TWO);
+            assert.ok(loaded.some(c => c.id === 'wh-001'));
+            assert.ok(loaded.some(c => c.id === 'wh-002'));
+        });
+        it('should delete a config by id', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            await saveWebhookConfig(makeConfig('wh-001'), configFile);
+            await saveWebhookConfig(makeConfig('wh-002'), configFile);
+            const deleted = await deleteWebhookConfig('wh-001', configFile);
+            assert.strictEqual(deleted, true);
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, 1);
+            assert.strictEqual(loaded[0].id, 'wh-002');
+        });
+        it('should return false when deleting non-existent id', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            await saveWebhookConfig(makeConfig('wh-001'), configFile);
+            const deleted = await deleteWebhookConfig('wh-999', configFile);
+            assert.strictEqual(deleted, false);
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, 1);
+        });
+        it('should filter out malformed entries on load', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            const mixed = [makeConfig('wh-001'), { bad: 'entry' }, null, makeConfig('wh-002')];
+            writeFileSync(configFile, JSON.stringify(mixed), 'utf-8');
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, COUNT_TWO);
+        });
+        it('should filter out entries with invalid authMethod', async () => {
+            const configFile = join(tempDir, 'webhook-configs.json');
+            const entries = [
+                makeConfig('wh-valid'),
+                { ...makeConfig('wh-bad-auth'), authMethod: 'oauth2' },
+                { ...makeConfig('wh-bad-auth2'), authMethod: '' },
+            ];
+            writeFileSync(configFile, JSON.stringify(entries), 'utf-8');
+            const loaded = await loadWebhookConfigs(configFile);
+            assert.strictEqual(loaded.length, 1);
+            assert.strictEqual(loaded[0].id, 'wh-valid');
+        });
+    });
+    describe('isValidWebhookConfig', () => {
+        it('should accept a valid config', () => {
+            assert.strictEqual(isValidWebhookConfig({
+                id: 'wh-1', name: 'Test', authMethod: 'hmac-sha256', enabled: true, createdAt: '2026-01-01T00:00:00Z',
+            }), true);
+        });
+        it('should accept a valid config with optional secret', () => {
+            assert.strictEqual(isValidWebhookConfig({
+                id: 'wh-2', name: 'Test', authMethod: 'hmac-sha256', secret: 's3cret', enabled: true, createdAt: '2026-01-01T00:00:00Z',
+            }), true);
+        });
+        it('should reject null and non-objects', () => {
+            assert.strictEqual(isValidWebhookConfig(null), false);
+            assert.strictEqual(isValidWebhookConfig(undefined), false);
+            assert.strictEqual(isValidWebhookConfig('string'), false);
+            assert.strictEqual(isValidWebhookConfig(VALUE_FORTY_TWO), false);
+        });
+        it('should reject missing required fields', () => {
+            assert.strictEqual(isValidWebhookConfig({ name: 'X', authMethod: 'none', enabled: true, createdAt: '2026-01-01T00:00:00Z' }), false);
+            assert.strictEqual(isValidWebhookConfig({ id: '1', authMethod: 'none', enabled: true, createdAt: '2026-01-01T00:00:00Z' }), false);
+            assert.strictEqual(isValidWebhookConfig({ id: '1', name: 'X', enabled: true, createdAt: '2026-01-01T00:00:00Z' }), false);
+            assert.strictEqual(isValidWebhookConfig({ id: '1', name: 'X', authMethod: 'none', createdAt: '2026-01-01T00:00:00Z' }), false);
+            assert.strictEqual(isValidWebhookConfig({ id: '1', name: 'X', authMethod: 'none', enabled: true }), false);
+        });
+        it('should reject wrong field types', () => {
+            const base = { id: '1', name: 'X', authMethod: 'bearer', enabled: true, createdAt: '2026-01-01T00:00:00Z' };
+            assert.strictEqual(isValidWebhookConfig({ ...base, id: 123 }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, name: 42 }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, enabled: 'true' }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, createdAt: 0 }), false);
+        });
+        it('should reject wrong types for optional fields', () => {
+            const base = { id: '1', name: 'X', authMethod: 'bearer', enabled: true, createdAt: '2026-01-01T00:00:00Z' };
+            assert.strictEqual(isValidWebhookConfig({ ...base, secret: 42 }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, secret: null }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, bearerToken: true }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, bearerToken: null }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, apiKey: [] }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, apiKey: null }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, updatedAt: 42 }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, updatedAt: null }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, allowedIps: 'evil' }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, allowedIps: [1, COUNT_TWO] }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, allowedIps: [''] }), false);
+        });
+        it('should reject invalid authMethod values', () => {
+            const base = { id: '1', name: 'X', enabled: true, createdAt: '2026-01-01T00:00:00Z' };
+            assert.strictEqual(isValidWebhookConfig({ ...base, authMethod: 'oauth2' }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, authMethod: '' }), false);
+            assert.strictEqual(isValidWebhookConfig({ ...base, authMethod: 42 }), false);
+        });
+        it('should accept all valid authMethod values', () => {
+            const base = { id: '1', name: 'X', enabled: true, createdAt: '2026-01-01T00:00:00Z' };
+            for (const method of ['hmac-sha256', 'bearer', 'api-key', 'none']) {
+                assert.strictEqual(isValidWebhookConfig({ ...base, authMethod: method }), true);
+            }
+        });
+    });
+});
+//# sourceMappingURL=evaluation-hooks.test.js.map