observability-toolkit 2.0.0 → 2.1.1

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

@@ -0,0 +1,658 @@
+/**
+ * Evaluation Hooks Executor (Phase 4e)
+ *
+ * Handles external evaluator webhook payloads:
+ * - HMAC signature validation
+ * - Payload parsing and validation
+ * - Writing evaluations to JSONL files
+ */
+import { createHmac, timingSafeEqual } from 'crypto';
+import { appendFile, mkdir, open, writeFile, readFile, rename, unlink } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { normalizeScore, hookStatsSchema, webhookConfigSchema, } from './evaluation-hooks-schemas.js';
+import { GENAI_EVALUATION_ATTRIBUTES, GENAI_AGENT_ATTRIBUTES, GENAI_RESPONSE_ATTRIBUTES, AGENT_JUDGE_ATTRIBUTES, evaluatorTypeSchema, stepScoreSchema, toolVerificationSchema } from '../../backends/index.js';
+import { HOOK_RESPONSE_TEXT_LENGTH, MAX_NAME_LENGTH, MAX_SESSION_ID_LENGTH, MAX_STEP_SCORES, MAX_TOOL_VERIFICATIONS, DEFAULT_BATCH_SIZE, } from '../core/constants.js';
+import { getDateString } from '../core/file-utils.js';
+import { MAX_BATCH_BYTES, MAX_SINGLE_EVALUATION_BYTES, MAX_DEDUP_CACHE_SIZE, MAX_METADATA_KEYS, MAX_METADATA_KEY_LENGTH, STATS_FILE_NAME, WEBHOOK_CONFIGS_FILE_NAME, } from './llm-judge-constants.js';
+export { DEFAULT_BATCH_SIZE, MAX_BATCH_BYTES, MAX_SINGLE_EVALUATION_BYTES, MAX_METADATA_KEYS, MAX_METADATA_KEY_LENGTH, STATS_FILE_NAME, WEBHOOK_CONFIGS_FILE_NAME, };
+/**
+ * Statistics tracking for hook processing
+ */
+let hookStats = {
+    totalReceived: 0,
+    successCount: 0,
+    validationFailures: 0,
+    signatureFailures: 0,
+    deduplicatedCount: 0,
+};
+/**
+ * Deduplication cache: stores seen evaluation keys (responseId:evaluationName)
+ * with insertion-order iteration for LRU eviction.
+ */
+const dedupCache = new Set();
+const JSON_FILE_INDENT_SPACES = 2;
+const SHA256_SIGNATURE_PREFIX = 'sha256=';
+const SHA256_SIGNATURE_PREFIX_LENGTH = SHA256_SIGNATURE_PREFIX.length;
+const SENSITIVE_FILE_MODE_OWNER_ONLY = 0o600;
+/**
+ * Build dedup key from payload. Returns undefined if responseId is missing
+ * (dedup requires a stable identifier). Uses null byte separator to prevent
+ * key collisions between responseId and evaluationName values containing
+ * the delimiter character.
+ */
+function buildDedupKey(payload) {
+    if (!payload.responseId)
+        return undefined;
+    return `${payload.responseId}\0${payload.evaluationName}`;
+}
+/**
+ * Check if an evaluation is a duplicate. Returns true if already seen.
+ * Adds the key to the cache if not a duplicate. Uses delete+add on hits
+ * to maintain true LRU ordering (Set iterates in insertion order).
+ *
+ * Concurrency note: All operations are synchronous (no await points),
+ * so no interleaving is possible in Node.js single-threaded event loop.
+ */
+function isDuplicate(key) {
+    if (dedupCache.has(key)) {
+        // Move to end for true LRU semantics
+        dedupCache.delete(key);
+        dedupCache.add(key);
+        return true;
+    }
+    // LRU eviction: remove oldest entry when cache is full
+    if (dedupCache.size >= MAX_DEDUP_CACHE_SIZE) {
+        const oldest = dedupCache.values().next().value;
+        if (oldest !== undefined)
+            dedupCache.delete(oldest);
+    }
+    dedupCache.add(key);
+    return false;
+}
+/**
+ * Reset hook statistics (for testing)
+ */
+export function resetHookStats() {
+    hookStats = {
+        totalReceived: 0,
+        successCount: 0,
+        validationFailures: 0,
+        signatureFailures: 0,
+        deduplicatedCount: 0,
+    };
+    dedupCache.clear();
+}
+/**
+ * Get current hook statistics
+ */
+export function getHookStats() {
+    return { ...hookStats };
+}
+/**
+ * Persist current hook stats to a JSON file.
+ * Call after processing to survive restarts.
+ * @throws On write failure (ENOENT, EACCES, etc.) — caller is responsible for handling.
+ * Counterpart {@link loadPersistedHookStats} silently ignores read errors by design.
+ */
+export async function persistHookStats(statsFilePath) {
+    await writeFile(statsFilePath, JSON.stringify(hookStats, null, JSON_FILE_INDENT_SPACES), {
+        encoding: 'utf-8',
+        mode: SENSITIVE_FILE_MODE_OWNER_ONLY,
+    });
+}
+/**
+ * Load previously persisted hook stats from a JSON file.
+ * Replaces current in-memory stats. Call at startup to restore prior counts.
+ * Silently ignores missing or malformed files (ENOENT, SyntaxError).
+ * Counterpart {@link persistHookStats} throws on write failure by design.
+ * @throws {NodeJS.ErrnoException | Error} On permission errors (EACCES), invalid path (EISDIR),
+ *   or other unexpected errors. Does NOT throw for ENOENT or SyntaxError.
+ */
+export async function loadPersistedHookStats(statsFilePath) {
+    try {
+        const raw = await readFile(statsFilePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const result = hookStatsSchema.safeParse(parsed);
+        if (result.success) {
+            hookStats = result.data;
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT' && !(err instanceof SyntaxError)) {
+            throw err;
+        }
+        // ENOENT or SyntaxError — keep current stats
+    }
+}
+/**
+ * Load all webhook configs from a JSON file.
+ * Returns empty array if file doesn't exist or is malformed.
+ * Re-throws unexpected errors (EACCES, etc.).
+ * @throws {NodeJS.ErrnoException | Error} On permission errors (EACCES), invalid path (EISDIR),
+ *   or other unexpected errors. Does NOT throw for ENOENT or SyntaxError.
+ */
+export async function loadWebhookConfigs(configFilePath) {
+    try {
+        const raw = await readFile(configFilePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        const results = [];
+        for (const item of parsed) {
+            const result = webhookConfigSchema.safeParse(item);
+            if (result.success) {
+                results.push(result.data);
+            }
+        }
+        return results;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT' && !(err instanceof SyntaxError)) {
+            throw err;
+        }
+        return [];
+    }
+}
+/**
+ * Save (upsert) a webhook config by id.
+ * Sets file permissions to 0o600 since configs may contain secrets.
+ * Not safe for concurrent callers — uses read-modify-write without a lock.
+ * Callers must serialize access (e.g., single-threaded MCP tool handler).
+ */
+export async function saveWebhookConfig(config, configFilePath) {
+    const configs = await loadWebhookConfigs(configFilePath);
+    const idx = configs.findIndex(c => c.id === config.id);
+    if (idx >= 0) {
+        configs[idx] = config;
+    }
+    else {
+        configs.push(config);
+    }
+    await writeConfigFileAtomic(configFilePath, configs);
+}
+/**
+ * Delete a webhook config by id.
+ * Returns true if found and deleted, false if not found.
+ * Not safe for concurrent callers — uses read-modify-write without a lock.
+ * Callers must serialize access (e.g., single-threaded MCP tool handler).
+ */
+export async function deleteWebhookConfig(id, configFilePath) {
+    const configs = await loadWebhookConfigs(configFilePath);
+    const filtered = configs.filter(c => c.id !== id);
+    if (filtered.length === configs.length)
+        return false;
+    await writeConfigFileAtomic(configFilePath, filtered);
+    return true;
+}
+/**
+ * Atomic write: open tmp with owner-only mode at O_CREAT time → write → close → rename.
+ * Permissions are set at file creation (not post-hoc chmod), so secrets are never
+ * world-readable at any point. Close is in an inner `finally` to guarantee fd release.
+ * The outer `catch` cleans up `.tmp` on any failure (writeFile OR rename), so a
+ * partial file with secrets is never left on disk.
+ */
+async function writeConfigFileAtomic(filePath, configs) {
+    const tmp = filePath + '.tmp';
+    const fh = await open(tmp, 'w', SENSITIVE_FILE_MODE_OWNER_ONLY);
+    try {
+        try {
+            await fh.writeFile(JSON.stringify(configs, null, JSON_FILE_INDENT_SPACES), 'utf-8');
+        }
+        finally {
+            await fh.close();
+        }
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+}
+/**
+ * Type guard for WebhookConfig — delegates to webhookConfigSchema for single source of truth.
+ */
+export function isValidWebhookConfig(value) {
+    return webhookConfigSchema.safeParse(value).success;
+}
+/**
+ * Verify HMAC-SHA256 signature
+ *
+ * @param payload - Raw payload string
+ * @param signature - Expected signature (format: "sha256=<hex>")
+ * @param secret - HMAC secret
+ * @returns Verification result
+ */
+export function verifyHmacSignature(payload, signature, secret) {
+    if (!signature) {
+        return { valid: false, error: 'Missing signature header' };
+    }
+    if (!signature.startsWith(SHA256_SIGNATURE_PREFIX)) {
+        return { valid: false, error: 'Invalid signature format (expected sha256=<hex>)' };
+    }
+    const expectedHex = signature.slice(SHA256_SIGNATURE_PREFIX_LENGTH); // Remove "sha256=" prefix
+    // SHA-256 produces 32 bytes = 64 hex characters
+    if (!/^[a-f0-9]{64}$/i.test(expectedHex)) {
+        return {
+            valid: false,
+            error: `Invalid signature hex encoding (expected 64 hex chars, got ${expectedHex.length})`,
+        };
+    }
+    const computed = createHmac('sha256', secret).update(payload).digest('hex');
+    // Use timing-safe comparison to prevent timing attacks
+    const expectedBuffer = Buffer.from(expectedHex, 'hex');
+    const computedBuffer = Buffer.from(computed, 'hex');
+    if (expectedBuffer.length !== computedBuffer.length) {
+        hookStats.signatureFailures++;
+        return { valid: false, error: 'Signature length mismatch', algorithm: 'sha256' };
+    }
+    const valid = timingSafeEqual(expectedBuffer, computedBuffer);
+    if (!valid) {
+        hookStats.signatureFailures++;
+        return { valid: false, error: 'Signature mismatch', algorithm: 'sha256' };
+    }
+    return { valid: true, algorithm: 'sha256' };
+}
+/**
+ * Validate a single evaluation payload
+ */
+export function validateEvaluationPayload(payload, index) {
+    const errors = [];
+    // Check total payload size to prevent memory exhaustion
+    try {
+        const payloadSize = Buffer.byteLength(JSON.stringify(payload), 'utf-8');
+        if (payloadSize > MAX_SINGLE_EVALUATION_BYTES) {
+            errors.push({
+                index,
+                field: 'payload',
+                message: `Evaluation payload size (${payloadSize} bytes) exceeds maximum (${MAX_SINGLE_EVALUATION_BYTES} bytes)`,
+                suggestion: 'Reduce metadata size or split into multiple evaluations',
+            });
+            return errors; // Early return - no point validating further
+        }
+    }
+    catch {
+        // If serialization fails, payload is invalid
+        errors.push({
+            index,
+            field: 'payload',
+            message: 'Evaluation payload cannot be serialized (circular reference or invalid data)',
+        });
+        return errors;
+    }
+    // Required: evaluationName
+    if (!payload.evaluationName || typeof payload.evaluationName !== 'string') {
+        errors.push({
+            index,
+            field: 'evaluationName',
+            message: 'evaluationName is required and must be a non-empty string',
+            suggestion: 'Provide an evaluation metric name (e.g., "relevance", "faithfulness")',
+        });
+    }
+    else if (payload.evaluationName.length > MAX_NAME_LENGTH) {
+        errors.push({
+            index,
+            field: 'evaluationName',
+            message: `evaluationName exceeds maximum length (${MAX_NAME_LENGTH} characters)`,
+        });
+    }
+    // Required: evaluator
+    if (!payload.evaluator || typeof payload.evaluator !== 'string') {
+        errors.push({
+            index,
+            field: 'evaluator',
+            message: 'evaluator is required and must be a non-empty string',
+            suggestion: 'Provide evaluator identity (e.g., "claude-3-sonnet", "human-reviewer-001")',
+        });
+    }
+    else if (payload.evaluator.length > MAX_NAME_LENGTH) {
+        errors.push({
+            index,
+            field: 'evaluator',
+            message: `evaluator exceeds maximum length (${MAX_NAME_LENGTH} characters)`,
+        });
+    }
+    // Required: evaluatorType
+    const validTypes = evaluatorTypeSchema.options;
+    if (!payload.evaluatorType || !validTypes.includes(payload.evaluatorType)) {
+        errors.push({
+            index,
+            field: 'evaluatorType',
+            message: `evaluatorType must be one of: ${validTypes.join(', ')}`,
+            suggestion: 'Specify the type of evaluator',
+        });
+    }
+    // At least one of scoreValue or scoreLabel required
+    const hasScoreValue = payload.scoreValue !== undefined && payload.scoreValue !== null;
+    const hasScoreLabel = payload.scoreLabel !== undefined && payload.scoreLabel !== null;
+    if (!hasScoreValue && !hasScoreLabel) {
+        errors.push({
+            index,
+            field: 'scoreValue/scoreLabel',
+            message: 'At least one of scoreValue or scoreLabel is required',
+            suggestion: 'Provide scoreValue (numeric 0-1) or scoreLabel (e.g., "pass", "fail")',
+        });
+    }
+    // Note: scoreValue finiteness is enforced by evaluationResultSchema (.finite())
+    // Validate text field lengths
+    if (payload.explanation && payload.explanation.length > HOOK_RESPONSE_TEXT_LENGTH) {
+        errors.push({
+            index,
+            field: 'explanation',
+            message: `explanation exceeds maximum length (${HOOK_RESPONSE_TEXT_LENGTH} characters)`,
+        });
+    }
+    // Validate optional ID fields
+    const idFields = ['responseId', 'traceId', 'sessionId', 'agentId'];
+    for (const field of idFields) {
+        const value = payload[field];
+        if (value !== undefined && value !== null) {
+            if (typeof value !== 'string') {
+                errors.push({ index, field, message: `${field} must be a string` });
+            }
+            else if (value.length > MAX_SESSION_ID_LENGTH) {
+                errors.push({
+                    index,
+                    field,
+                    message: `${field} exceeds maximum length (${MAX_SESSION_ID_LENGTH} characters)`,
+                });
+            }
+        }
+    }
+    // Validate agentName
+    if (payload.agentName !== undefined && payload.agentName !== null) {
+        if (typeof payload.agentName !== 'string') {
+            errors.push({ index, field: 'agentName', message: 'agentName must be a string' });
+        }
+        else if (payload.agentName.length > MAX_NAME_LENGTH) {
+            errors.push({ index, field: 'agentName', message: `agentName exceeds maximum length (${MAX_NAME_LENGTH} characters)` });
+        }
+    }
+    // Validate stepScores
+    if (payload.stepScores !== undefined) {
+        if (!Array.isArray(payload.stepScores)) {
+            errors.push({ index, field: 'stepScores', message: 'stepScores must be an array' });
+        }
+        else if (payload.stepScores.length > MAX_STEP_SCORES) {
+            errors.push({
+                index,
+                field: 'stepScores',
+                message: `stepScores exceeds maximum length (${MAX_STEP_SCORES} items)`,
+            });
+        }
+        else {
+            for (let i = 0; i < payload.stepScores.length; i++) {
+                const step = payload.stepScores[i];
+                if (!stepScoreSchema.safeParse(step).success) {
+                    errors.push({
+                        index,
+                        field: `stepScores[${i}]`,
+                        message: 'Invalid step score: requires step (string|number) and score (number 0-1)',
+                    });
+                }
+            }
+        }
+    }
+    // Validate toolVerifications
+    if (payload.toolVerifications !== undefined) {
+        if (!Array.isArray(payload.toolVerifications)) {
+            errors.push({ index, field: 'toolVerifications', message: 'toolVerifications must be an array' });
+        }
+        else if (payload.toolVerifications.length > MAX_TOOL_VERIFICATIONS) {
+            errors.push({
+                index,
+                field: 'toolVerifications',
+                message: `toolVerifications exceeds maximum length (${MAX_TOOL_VERIFICATIONS} items)`,
+            });
+        }
+        else {
+            for (let i = 0; i < payload.toolVerifications.length; i++) {
+                const result = toolVerificationSchema.safeParse(payload.toolVerifications[i]);
+                if (!result.success) {
+                    errors.push({
+                        index,
+                        field: `toolVerifications[${i}]`,
+                        message: `Invalid tool verification: ${result.error.issues[0].message}`,
+                    });
+                }
+            }
+        }
+    }
+    // Validate trajectoryLength
+    if (payload.trajectoryLength !== undefined) {
+        if (typeof payload.trajectoryLength !== 'number' || !Number.isFinite(payload.trajectoryLength)) {
+            errors.push({ index, field: 'trajectoryLength', message: 'trajectoryLength must be a finite number' });
+        }
+        else if (payload.trajectoryLength < 0) {
+            errors.push({ index, field: 'trajectoryLength', message: 'trajectoryLength cannot be negative' });
+        }
+    }
+    return errors;
+}
+/**
+ * Convert a webhook payload to JSONL record format
+ */
+export function payloadToJsonlRecord(payload, timestamp) {
+    const ts = timestamp || new Date().toISOString();
+    // Normalize score if unit is provided
+    let normalizedScore = payload.scoreValue;
+    if (normalizedScore !== undefined && payload.scoreUnit) {
+        normalizedScore = normalizeScore(normalizedScore, payload.scoreUnit);
+    }
+    const attributes = {
+        [GENAI_EVALUATION_ATTRIBUTES.NAME]: payload.evaluationName,
+        [GENAI_EVALUATION_ATTRIBUTES.EVALUATOR]: payload.evaluator,
+        [GENAI_EVALUATION_ATTRIBUTES.EVALUATOR_TYPE]: payload.evaluatorType,
+    };
+    // Optional attributes
+    if (normalizedScore !== undefined) {
+        attributes[GENAI_EVALUATION_ATTRIBUTES.SCORE_VALUE] = normalizedScore;
+    }
+    if (payload.scoreLabel) {
+        attributes[GENAI_EVALUATION_ATTRIBUTES.SCORE_LABEL] = payload.scoreLabel;
+    }
+    if (payload.scoreUnit) {
+        attributes[GENAI_EVALUATION_ATTRIBUTES.SCORE_UNIT] = payload.scoreUnit;
+    }
+    if (payload.explanation) {
+        attributes[GENAI_EVALUATION_ATTRIBUTES.EXPLANATION] = payload.explanation;
+    }
+    if (payload.responseId) {
+        attributes[GENAI_RESPONSE_ATTRIBUTES.ID] = payload.responseId;
+    }
+    if (payload.sessionId) {
+        attributes['session.id'] = payload.sessionId;
+    }
+    // Agent-as-Judge fields
+    if (payload.agentId) {
+        attributes[GENAI_AGENT_ATTRIBUTES.AGENT_ID] = payload.agentId;
+    }
+    if (payload.agentName) {
+        attributes[GENAI_AGENT_ATTRIBUTES.AGENT_NAME] = payload.agentName;
+    }
+    if (payload.stepScores) {
+        attributes[AGENT_JUDGE_ATTRIBUTES.STEP_SCORES] = JSON.stringify(payload.stepScores);
+    }
+    if (payload.toolVerifications) {
+        attributes[AGENT_JUDGE_ATTRIBUTES.TOOL_VERIFICATIONS] = JSON.stringify(payload.toolVerifications);
+    }
+    if (payload.trajectoryLength !== undefined) {
+        attributes[AGENT_JUDGE_ATTRIBUTES.TRAJECTORY_LENGTH] = payload.trajectoryLength;
+    }
+    // Custom metadata — apply key count and key length guards (CR-M2)
+    if (payload.metadata) {
+        let keyCount = 0;
+        for (const [key, value] of Object.entries(payload.metadata)) {
+            if (keyCount >= MAX_METADATA_KEYS)
+                break;
+            if (key.length > MAX_METADATA_KEY_LENGTH)
+                continue;
+            // Prefix custom attributes to avoid collisions
+            attributes[`webhook.metadata.${key}`] = value;
+            keyCount++;
+        }
+    }
+    const record = {
+        timestamp: ts,
+        name: 'gen_ai.evaluation.result',
+        attributes,
+    };
+    // Add trace correlation if provided
+    if (payload.traceId) {
+        record.traceId = payload.traceId;
+    }
+    return JSON.stringify(record);
+}
+/**
+ * Process a single evaluation and write to JSONL file
+ */
+export async function processEvaluation(payload, options) {
+    hookStats.totalReceived++;
+    // Validate payload
+    const errors = validateEvaluationPayload(payload);
+    if (errors.length > 0) {
+        hookStats.validationFailures++;
+        return {
+            success: false,
+            message: 'Validation failed',
+            errors,
+        };
+    }
+    // Deduplication check (requires responseId for stable key)
+    if (options.deduplication) {
+        const key = buildDedupKey(payload);
+        if (key !== undefined && isDuplicate(key)) {
+            hookStats.deduplicatedCount++;
+            return {
+                success: true,
+                message: 'Duplicate evaluation skipped',
+                processedCount: 0,
+            };
+        }
+    }
+    // Ensure telemetry directory exists
+    if (!existsSync(options.telemetryDir)) {
+        await mkdir(options.telemetryDir, { recursive: true });
+    }
+    // Generate JSONL record
+    const timestamp = new Date().toISOString();
+    const record = payloadToJsonlRecord(payload, timestamp);
+    const date = getDateString();
+    const filePath = join(options.telemetryDir, `evaluations-${date}.jsonl`);
+    // Append to file
+    try {
+        await appendFile(filePath, record + '\n', 'utf-8');
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Failed to write evaluation: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    hookStats.successCount++;
+    hookStats.lastProcessedAt = timestamp;
+    return {
+        success: true,
+        message: 'Evaluation stored successfully',
+        processedCount: 1,
+    };
+}
+/**
+ * Process a batch of evaluations
+ */
+export async function processBatch(batch, options) {
+    const maxBatch = options.maxBatchSize || DEFAULT_BATCH_SIZE;
+    if (!batch.evaluations || !Array.isArray(batch.evaluations)) {
+        return {
+            success: false,
+            message: 'Invalid batch payload: evaluations must be an array',
+        };
+    }
+    if (batch.evaluations.length === 0) {
+        return {
+            success: false,
+            message: 'Empty batch: no evaluations provided',
+        };
+    }
+    if (batch.evaluations.length > maxBatch) {
+        return {
+            success: false,
+            message: `Batch too large: ${batch.evaluations.length} evaluations exceeds maximum of ${maxBatch}`,
+        };
+    }
+    hookStats.totalReceived += batch.evaluations.length;
+    // Validate all payloads first (includes individual size checks)
+    const allErrors = [];
+    for (let i = 0; i < batch.evaluations.length; i++) {
+        const errors = validateEvaluationPayload(batch.evaluations[i], i);
+        allErrors.push(...errors);
+    }
+    if (allErrors.length > 0) {
+        hookStats.validationFailures += batch.evaluations.length;
+        return {
+            success: false,
+            message: `Validation failed for ${allErrors.length} field(s)`,
+            errors: allErrors,
+        };
+    }
+    // Ensure telemetry directory exists
+    if (!existsSync(options.telemetryDir)) {
+        await mkdir(options.telemetryDir, { recursive: true });
+    }
+    // Generate JSONL records with progressive byte size check to prevent OOM
+    const timestamp = new Date().toISOString();
+    const date = getDateString();
+    const filePath = join(options.telemetryDir, `evaluations-${date}.jsonl`);
+    const records = [];
+    let totalBytes = 0;
+    let dedupSkipped = 0;
+    for (let i = 0; i < batch.evaluations.length; i++) {
+        // Deduplication check per evaluation in batch
+        if (options.deduplication) {
+            const key = buildDedupKey(batch.evaluations[i]);
+            if (key !== undefined && isDuplicate(key)) {
+                dedupSkipped++;
+                continue;
+            }
+        }
+        const record = payloadToJsonlRecord(batch.evaluations[i], timestamp);
+        const recordBytes = Buffer.byteLength(record, 'utf-8') + 1; // +1 for newline
+        totalBytes += recordBytes;
+        if (totalBytes > MAX_BATCH_BYTES) {
+            return {
+                success: false,
+                message: `Batch payload too large: ${totalBytes} bytes exceeds maximum ${MAX_BATCH_BYTES} bytes (failed at evaluation ${i + 1})`,
+            };
+        }
+        records.push(record);
+    }
+    if (dedupSkipped > 0) {
+        hookStats.deduplicatedCount += dedupSkipped;
+    }
+    const storedCount = records.length;
+    // Skip file write if all evaluations were deduplicated
+    if (storedCount > 0) {
+        const content = records.join('\n') + '\n';
+        // Write all at once
+        try {
+            await appendFile(filePath, content, 'utf-8');
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to write evaluations: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    hookStats.successCount += storedCount;
+    if (storedCount > 0) {
+        hookStats.lastProcessedAt = timestamp;
+    }
+    const dedupMsg = dedupSkipped > 0 ? ` (${dedupSkipped} duplicate(s) skipped)` : '';
+    return {
+        success: true,
+        message: `Successfully stored ${storedCount} evaluation(s)${dedupMsg}`,
+        processedCount: storedCount,
+    };
+}
+//# sourceMappingURL=evaluation-hooks.js.map